Use the Appcues JavaScript object to identify users, track events, and control experiences programmatically.

Load the SDK

When the Appcues script loads, it attaches an Appcues object to window. You can call methods as window.Appcues.methodName() or just Appcues.methodName().

The script loads asynchronously, so Appcues is not available immediately. If you call Appcues.identify() before the SDK finishes loading, it throws Appcues is not defined. Handle this in one of three ways:

To check whether the SDK has loaded before calling it:

if (typeof window.Appcues !== 'undefined') {
  Appcues.identify('user-123');
}

Single-page applications

If you're using React, Next.js, Vue, Angular, or another SPA, set enableURLDetection: true in window.AppcuesSettings. The SDK detects route changes automatically — you don't need to call Appcues.page() manually. See Install the Appcues SDK for full details.

Methods

Appcues.identify(userId, [properties])

Identify the current user. This is required — Appcues won't show experiences until you call it. It also triggers a page() call automatically.

Property values can be strings, numbers, or booleans. Any identify call with an array or nested object as a property value will not appear in your Appcues account.

Note: Send createdAt as a Unix timestamp in seconds, not milliseconds.

Appcues.identify("1234", {
  name: "Jonathan",
  createdAt: 1578700800,
  company: "Appcues"
});

Appcues.group(groupId, [properties])

Associate the current user with a group (company or account). A user can belong to multiple groups, but only one is active at a time. Only the most recently associated group is considered for targeting.

Appcues.group("6789", {
  company_name: "Lendi Global",
  plan_level: "enterprise",
  employee_count: 12000,
  in_trial: false
});

Appcues.anonymous()

Generate a session-based unique ID for the current user when you don't have a real user ID.

Warning: Each new session creates a new anonymous ID, which can significantly increase your MAU count. Read the anonymous users overview before implementing.

Appcues.anonymous();

Appcues.page()

Notify the SDK that the page or application state has changed. Call this on route changes in single-page applications if you haven't enabled enableURLDetection.

Appcues.page();

Appcues.track(eventName, [eventProperties])

Track a custom event with optional properties. Use tracked events to trigger Flows, complete Checklist items, and measure Goals.

The event name is used as the identifier — changing the format or convention of an event name causes it to be ingested as a different event.

Note: Audience targeting based on event properties is not currently supported. Event properties can be used for filtering in Event Triggering (Enterprise plans only).

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

Appcues.show(contentId)

Force a specific experience to display by its content ID, ignoring all targeting and frequency rules.

When used with Checklists, the force-shown Checklist takes precedence over others and reappears even if previously dismissed. If the Checklist was already shown to the user, the congratulations content will not appear upon completion.

Find the contentId in the URL while editing your experience, for example: https://studio.appcues.com/flows/3344b86d-53d6-4b80-9306-1d8ffb73e55b/analytics

Appcues.show("-ABCD123");

Appcues.clearShow()

Stop force-showing Checklists triggered by show().

Appcues.clearShow();

Appcues.on(eventName, callbackFn, [context])

Listen for SDK events. Register a callback that fires each time the specified event occurs.

Supported events:

• 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, like clicking "Next"
• 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

The callback receives an event object. For the all event, the callback receives (eventName, event) instead. The event object looks like:

{"id":"step_attempted","name":"Step Attempted","flowId":"-L75x7dkvlvGcgIbMPSI","flowName":"Dropdown test","flowType":"journey","flowVersion":1522433413154,"timestamp":1555451877992,"sessionId":1555451877688,"stepId":"-L75xBtqpP8W4QUualko","stepType":"modal"}

Appcues.on("flow_started", function(event) {
  console.log("Flow started: " + event.flowId);
});

// Listen for all events
Appcues.on("all", function(eventName, event) {
  console.log(eventName, event);
});

For a more detailed look at Appcues.on, see Working with Client-Side Appcues Events. For a complete list of SDK events, see the Flow Events Reference.

Appcues.off(eventName, callbackFn, [context])

Remove a previously registered event listener.

Appcues.off("flow_started", myCallback);

Appcues.once(eventName, callbackFn, [context])

Register a callback that fires only once, on the next matching event.

Appcues.once("flow_started", function() {
  console.log("First flow started.");
});

Appcues.reset()

Clear all user data and in-progress Flows for the current session. Call this when a user logs out.

Caution: If you call reset() followed by anonymous(), the SDK generates a new anonymous ID — which can cause the same Flow to display again.

Appcues.reset();

Appcues.debug()

Enable the Appcues debug panel for detailed SDK state and event information. Pass false to disable.

Appcues.debug();

// Disable debug mode
Appcues.debug(false);