Javascript API (Developer)

The Appcues Javascript SDK officially supports the following methods as part of its API:

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 only one group can be identified 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).

Example:

Appcues.track("Clicked button", {
    color: "red",
    buttonText: "Get started"
});

show (contentId)

Forces specific Appcues content to appear for the current user by passing in the ID. This method ignores any targeting that is set on the flow or checklist. A checklist that has been force shown will take precedent 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.

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. The 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.

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 it would wipe the generated ID for that anon guest. 

Example:

Appcues.reset();

debug (enable = true)

Puts the SDK in debug mode, showing more information about the SDK's inner workings.

Example:

Appcues.debug();