Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Contact Us
  • Home
  • Installation & Developers
  • API & Data

Javascript API (Developer)

Updated at December 16th, 2022

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Installation & Developers
    Installing Appcues Installing Appcues Mobile API & Data Troubleshooting Extras
  • User Experiences
    Web Experiences Building Web Experiences Building Mobile Experiences Customization & Styling Targeting Studio Troubleshooting Use Cases FAQ
  • Mobile
    Installation & Overview Building Mobile Experiences Mobile Analytics Troubleshooting
  • Account Management
    Subscription Users & Data
  • Analytics
    Experience and Event Analytics Data
  • Best Practices
    Use Cases Pro Tips PLG FAQ
  • Integrations
    Integration Documents Use Cases Resources
  • Post-mortem
    System Incidents
+ More

Table of Contents

contentId

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 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. 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();

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Appcues Installation Overview
  • User Properties Overview
  • Welcome and Getting Started
  • Installing Appcues Asynchronously (Developer)
Appcues logo

Product

Why Appcues
How it works
Integrations
Security
Pricing
What's new

Use cases

User Onboarding Software
Feature Adoption Software
NPS & Surveys
Announcements
Insights
Mobile Adoption

Company

About
Careers
we're Hiring

Support

Developer Docs
Contact

Resources

The Appcues Blog
Product Adoption Academy
GoodUX
Case studies
Webinar Series
Made with Appcues
Appcues University

Follow us

Facebook iconTwitter icon greyLinkedin iconInstagram icon
© 2022 Appcues. All rights reserved.
SecurityTerms of ServicePrivacy Policy
Expand