Javascript API (Developer)
Learn more about our Javascript API and how you can use it to identify users, trigger content or debug your installation.
Table of Contents
The Appcues Javascript SDK officially supports the following methods as part of its API:
Identify
identify (userId, [properties])
Identifies the current user with an ID and an optional set of properties. Behind the scenes, this call also invokes Appcues.page(). This is the one call that is required for Appcues to load and function on your site. Property values can be strings, numbers, or booleans. Beware! Any identify call with an array or nested object as a property value will not appear in your Appcues account.
Example:
Appcues.identify("1234", {
name: "Jonathan",
createdAt: 578721600000,
company: "Appcues"
})
group (groupId, [properties])
Identifies the current group (the user's account, company, etc.) of the user with an ID and an optional set of properties. Property values can be strings, numbers, or booleans. A user can belong to multiple groups, but can only be associated with one at a time. Only the group most recently associated with the user will be considered for targeting.
Appcues.group("6789", {
company_name: "Lendi Global",
plan_level: "enterprise",
employee_count: 12000,
in_trial: false
})
anonymous
Generates a session-based unique ID for the current user. Use of this call will likely drive up your MAU's, so be sure to read this overview before implementing.
Example:
Appcues.anonymous();
page
Notifies the SDK that the state of the application has changed. You can use this to let us know when the URL has changed.
Example:
Appcues.page();
track (eventName, [eventProperties])
Tracks a custom event (by name) taken by the current user, along with any properties about that event. Currently, we do not support audience targeting based on event properties. They can however be used for filtering events in our Event Triggering feature (available on Enterprise plans only).
As the event name is used as the event identifier, changing the format or convention of an event name will cause it to be ingested as a different event.
Example:
Appcues.track("Clicked button", {
color: "red",
buttonText: "Get started"
});
show (contentId)
Forces specific Appcues content—flows, checklists, or NPS surveys—to appear for the current user by passing in the content ID. This method ignores any targeting that is set on the flow or checklist. A checklist that has been force-shown will take precedence over any other checklists. The checklist will show even if it was previously dismissed. If used for a checklist that's already been shown to the user, the 'Congratulations' content will not appear upon completion.
contentId
References the specific internal Appcues ID of the flow, checklist, or NPS experience within Appcues Studio. The IDs of each can be found within the URL for each experience.
Example:
Appcues.show("-ABCD123");
clearShow ()
Stops force showing any checklists shown using Appcues.show.
Example:
Appcues.clearShow();
on (eventName, callbackFn, [context])
Fire the callback function when the given event is triggered by the SDK. Some examples of events triggered by the SDK include:
- flow_started — a flow is first started
- flow_completed — a flow is completed
- flow_skipped — a flow is skipped
- step_interacted — a user interacts with a step in the flow, like clicking the "Next" button
- form_submitted — a form is submitted
- form_field_submitted — triggered for each individual field in the submitted form
- all — listen for all events emitted by the SDK
If eventName is all, callbackFn should be a function(eventName, event). For all other values of eventName, callbackFn should be a function(event). The event will be an object that looks something like:
{"id":"step_attempted","name":"Step Attempted","flowId":"-L75x7dkvlvGcgIbMPSI","flowName":"Dropdown test","flowType":"journey","flowVersion":1522433413154,"timestamp":1555451877992,"sessionId":1555451877688,"stepId":"-L75xBtqpP8W4QUualko","stepType":"modal"}
Usage example:
Appcues.on("flow_started", function(event) {
console.log("Appcues started a flow with ID " + event.flowId);
});
For a more detailed look at Appcues.on, check out our documentation here.
For a complete list of events triggered by the SDK, check out our documentation here.
off (eventName, callbackFn, [context])
Undoes a corresponding on call.
Example:
Appcues.off("flow_started");
once (eventName, callbackFn, [context])
Fire the callback function once the next time the given event is triggered by the SDK.
Example:
Appcues.once("flow_started", function() {
console.log("Appcues started a flow.");
});
reset
Clears all known information about the current user in this session. This call will clear the flow in progress and wipe any data we generate for a user. This is useful when your user logs out of your application.
Note: When used in conjunction with the Anonymous call this can cause flows to show twice, since the reset will wipe the generated ID for that anon guest and then a new anonymous ID will be generated by the Anonymous call.
Example:
Appcues.reset();
debug (enable = true)
Puts the SDK in debug mode, showing more information about the SDK's inner workings.
Example:
Appcues.debug();