Plugin events

The website plugin is event-based. Custom events are raised throughout the lifetime of the script, particularly during the address verification process.

The plugin uses these events internally, so even though these are like regular events used in Javascript, you should use the plugin's on() function to intercede so that your own handler is executed first. For example:

liveaddress.on("AddressAccepted", function(event, data, previousHandler)
	if (data.response.isMissingSecondary())
		alert("Don't forget your apartment number!");
		previousHandler(event, data);

Notice previousHandler in the above example. When you run a custom handler, you intercept the event. Calling previousHandler passes the event back to the original handler so it will run. In this example, previousHandler is placed inside of an else statement, because we want to pass the event back to the original handler only if the address is not missing a secondary number (an apartment or suite number). In most cases an else statement will not apply; you will want to call previousHandler(event, data) unconditionally.

We have created additional event handlers that you can use as a starting point.

Table of events

Event namePossible DataDescription
First, these fire in basically this order:
FieldsMappedProcess which maps address fields to elements on the page is complete.
MapInitializedMapped addresses are now wired up to their input/UI elements and are ready and waiting.
AutocompleteInvokedinput, addr, streetField, containerUiA request is about to be made to the auto-complete service.
AutocompleteReceivedinput, addr, streetField, containerUi, jsonA response was just received from the auto-complete service.
AddressChangedaddress, field, sourceEvent, suppressAutoVerification, valueA field's internal value within an address object has changed, usually because the user typed or changed their input in any mapped address field, or .set() was called on an Address object.
AutocompleteUsedaddr, suggestionA suggested address was used from the autocomplete service. Fires after RequestSubmitted if autoVerify is set to false due to asynchronicity.
VerificationInvokedaddressThe verification process for an address is about to begin.
RequestSubmittedaddressAn address was just sent to SmartyStreets API (asynchronously).
ResponseReceivedaddress, response, invokeResponse was barely received for an address; it is not yet examined.
RequestTimedOutaddress, invoke, statusThis event fires only if no response is received after a period of time.
Then any one of these, upon initial examination of the response:
AddressWasValidaddress, invoke, responseThe address matched only one valid address with no ambiguity.
AddressWasAmbiguousaddress, invoke, response, selectorsThe address matched at least two valid addresses, and ambiguity will need to be resolved.
AddressWasInvalidaddress, invoke, response, selectorsThe input could not be matched to any valid addresses; empty response.
AddressWasMissingInputaddress, invoke, response, selectorsThe input was missing input required for verificaiton (e.g., country, address1, locality, administrative area, postal code).
AddressWasMissingSecondaryaddress, invoke, response, selectorsThe input was missing a secondary number (e.g., apartment number, suite number).
If the input is ambiguous, invalid, missing a secondary number, or missing input, these could happen:
OriginalInputSelectedaddress, invoke, responseThe user chose to use their own input even though it's not valid (applies to: ambiguous or invalid).
UsedSuggestedAddressaddress, chosenCandidate, invoke, responseUser chose a suggested candidate address (applies to: ambiguous).
InvalidAddressRejectedaddress, invoke, responseUser chose to go back to try fixing the bad address (applies to: invalid).
In the end...
AddressAcceptedaddress, invoke, responseAn address was flagged as accepted; we're done with it unless it changes.
Completedaddress, invoke, responseThe process is finished, at least for now (or the user aborted).

Having trouble?

Take a look at these troubleshooting tips we put together with lots of love.