Installation Guide for Developers
Learn how to install, setup and use Appcues in your tech stack.
Table of Contents
A Complete Technical Guide for a Direct Web Installation
Our comprehensive outline for installing Appcues directly in your product. This technical guide will cover the process from start to finish, and highlight both the required and optional components involved to result in a valuable implementation for success with Appcues!
Installation requires an hour or more of work for a developer with knowledge of how their product tracks user properties and events. You will need access to your team's Appcues account to complete the installation.
Looking for a non-technical overview? Check that out here!
Interested in our data security measures? Please review our Trust Center for details.
This guide focuses on a direct Appcues installation in web applications, for information about other installation methods please check out the guides below:
Installing in a mobile application? Check out the Mobile SDK guide!
Before You Get Started
What Do We Mean by “Install”?
Appcues works by adding an SDK into your site and some JavaScript to your application which allows Appcues to show content you build to users on your existing pages. This script loads with the page and uses the user properties, group properties and events you send in to determine which users should see what content, and when they should see it. Once you install Appcues, you can publish content live to your users!
Installation Components Overview
There are a few key components that together create a successful Appcues installation. While this guide will cover these items in detail, below in a brief overview of what makes an Appcues installation:
- Add the Appcues SDK Script to your Product - Appcues is added to your product to connect to your Appcues account and show the content you’ve built
- Identify Users and Groups - Tell Appcues when a user is present, and send information about who that user is. This is used for targeting experiences and creating segments.
- Track Events - Tracking events with Appcues allows you to measure your users’ engagement with your product. These events can also be used for segmentation and targeting.
Video Overview
Ready to install? Continue through this guide for next steps!
Add the Appcues SDK Script
The Appcues SDK connects back to your Appcues account and allows for Appcues Javascript to function.
Place the following code snippet within the HTML <head></head> of your page(s). Your Appcues ID can be found in your Studio Settings Page (a copyable version of this snippet also exists in the In-Studio Guide).
<script type="text/javascript">
window.AppcuesSettings = { enableURLDetection: true };
</script>
<script src="//fast.appcues.com/YOUR_APPCUES_ID.js"></script>Make sure to add the script on every page you want to use Appcues on. This can be done by adding the SDK to your index.html file, another root file, or to specific pages if you’d like to have more control over which pages Appcues is loaded on.
By default, the enableURLDetection script accounts for any page changes across your product where Appcues will be installed. This is used to determine the user’s URL for effective flow targeting and cross-page experiences.
A Note on Using TypeScript
If you're using Typescript and are receiving an Appcues-related ‘does not exist’ error, you will need to ensure Appcues is declared as a global variable. One way to do this is with the following snippets:
declare global {
interface Window { Appcues: any; }
}
declare global {
interface Window { AppcuesSettings: any; }
}
Installing in a Single-Page Application (SPA)? You may not want to include the enableURLDetection script. Please refer to this doc for more information.
Interested in the Appcues SDK under your own domain? Check out this doc!
Identify Users and Groups
Appcues requires users be identified to show experiences and track events. Appcues only uses the data that you explicitly send in via identify(), group(), and select integrations.
Please Note: All unique users identified by Appcues within a rolling 30-day period are considered a Monthly Active User (MAU) regardless of whether they see an experience or not.
Whether you are installing on behalf of someone or working directly within your team, we encourage you to collaborate on and follow an Installation Plan to outline which properties to include.
Where Are identify() and group() Added?
Adding the SDK in the previous step connects your product to your Appcues account, but you still need to send data into Appcues. Before you add in the identify and group calls, here is a breakdown of where to add them in your codebase:
- Which file will you be adding the Appcues calls to? Appcues can be added directly into an existing file, or you can create a separate file to reference within your codebase.
- For consistent user identification, it is best to call identify() on page load (and subsequently any group() calls if utilizing Group data)
Identifying Users
Required: Identify individual users via Appcues.identify()
Components of identify()
-
Unique User ID (Required)
- Appcues recommends choosing opaque and hard-to-guess User IDs, such as a UUID. See the FAQ for Developers for more details about choosing a User ID.
- In some cases, we may need to consider using a global ID. If utilizing our integrations, there may be different requirements on what the User ID needs to be for successful integration. More details on this in the Other Considerations section.
-
Custom User Properties/User Attributes (Optional)
- While technically optional, we strongly encourage that you send additional data to Appcues to allow for greater targeting options for user experiences. Lack of custom properties greatly limits your Appcues use cases.
- Custom user properties will vary depending on your use cases and available data, but some common properties we see are CreatedAt, Role, Email, Language.
- If your User IDs are not easily recognizable to know who that user is, you can set a Display Identifier in Studio based on a custom user property. This does not impact your User ID, nor does this value need to be necessarily unique to each user; we recommend using Email, Full Name, or a similar property that your team will be able to easily recognize.
For more ways to send custom user properties to Appcues, check out our integrations!
Example identify() Call
This example utilizes hard-coded user information (no variable data). Please tailor this to reflect your own User ID and Custom Properties prior to committing in your codebase.
window.Appcues.identify(
“<<<USER_ID>>>”, // unique, required
{
// example custom user properties
createdAt: 1566932390, // Unix timestamp of user signup date
role: "Admin", // Current user’s role or permissions
firstName: "John", // current user's first name
email: "john.doe@example.com", // Current user's email
location: "90210", // for location-based targeting
version: "2.0", // for version-based targeting
language: "Spanish", // for multi-language applications
}
);
Notes on Identifying Users
- Ensure identify() is called prior to any
Appcues.page()calls. If not implemented this way, your end users could experience a delay due to events buffering while waiting on a user to be identified. - Do not send in a custom property named
UserId,user_ID, etc. as this will result in duplicate UserId fields in Appcues which can lead to confusing and tricky targeting. By default, the unique UserID that is listed first in youridentify()is labeled as User Id in Appcues and the label cannot be changed. - Properties sent via integrations – Whereas
identify()properties are sent live as the user is identified, properties from integrations are received through a sync and are not updated on eachidentify(). Because of this, anything that is immediately relevant to the user should be sent directly viaidentify(). - Looking to send in bulk user data? Check out the Appcues API!
If you need to ensure that only users you verify can send data to Appcues and see Appcues experiences targeted to them, consider setting up Identity Verification.
Identifying Groups
Recommended: Identify user groups, or accounts, via Appcues.group()
Components of group()
-
Group ID (required)
- The Group ID should be the unique value between each group, or account, to recognize one group from another. This could be an Account ID, Account Name, etc.
- If utilizing our integrations for group data, there may be different requirements on what the Group ID needs to be for successful integration. More details on this in the Other Considerations section.
- While Group Properties are typically used with B2B platforms to associate end users within an account or company, Group Properties can also be used to group individual users together based on shared attributes (Plan Type, etc.)
-
Custom Group Properties/Group Attributes
- The best Custom Group Properties are properties that are shared between users within that group/account, and that don’t change user to user within the account (user data should be sent via
identify()) - If your Group IDs are not easily recognizable to know which account that is, you can set a Display Identifier in Studio based on a custom group property. This does not impact your Group ID, nor does this value need to be necessarily unique to each account; we recommend using Company Name, Account Name, or a similar property that your team will be able to easily recognize.
- The best Custom Group Properties are properties that are shared between users within that group/account, and that don’t change user to user within the account (user data should be sent via
Example group() Call
This example utilizes hard-coded group information (no variable data). Please tailor this to reflect your own Group ID and Custom Group Properties prior to committing in your codebase.
window.Appcues.group(
"<<< GROUP_ID >>>", // unique, required
{
// example custom group properties
createdAt: 1566932390, // Unix timestamp of account signup date
purchasedAt: 1566932395, // Unix timestamp of account purchase date
planTier: "Standard", // Account's plan tier
companyName: "CoolCo", // Account's name
MRR: 599, // Account's monthly recurring revenue
renewalDate: "06202035" // Timestamp of upcoming account renewal date
accountmanager: "Jerry" // Account manager
});
Notes on Identifying Groups
- Ensure that identify() is called prior to group(), this is to properly identify the user then assign them to the group.
- A user can belong to multiple groups, but a user's activity is only associated with one group at a time. Only the group most recently associated with the user will be considered for targeting Appcues experiences.
- Looking to send in bulk group data? Check out the Appcues API!
Formatting User and Group Data
-
Keep Property Names Simple.
The Appcues UI will try to reformat the property name into something readable, so a property like "days_since_signup" becomes "Days Since Signup" and "planName" becomes "Plan Name". To make things easier on your non-technical colleagues, send in property names that are simple and clear. Avoid names like "property_1" or "base64UUID" unless that's a well-known label among your team. -
Send Numbers, Strings, and Booleans
Appcues targeting can only operate on numbers, strings, and booleans. You can send complex objects in your Appcues.identify() call, but they will be ignored. We don't recommend sending objects to Appcues as a user property. -
Don't Reformat Types
Send numbers as numbers, strings as strings, etc. Appcues uses type inference to match targeting criteria, so you don't need to think about types. This is really important when doing comparison, since the number 10 is greater than the number 2, but the opposite is true if those values are converted to strings.
In the same vein, if a value is undefined or null, either don't send it to Appcues, or send it as null. Do not send an empty string for any non-existent value. Additionally, string properties are case sensitive.
Lastly, make sure that each user property has a consistent type. As an example, "signup_date" (and date properties in general) must either be sent as a non-fractional timestamp (number) or as an ISO date (string). Whichever you choose, make sure to be consistent every time that value is sent to Appcues. Inconsistency could result in over- or under-targeting content to users.
Appcues uses UNIX Epoch timestamps for dates and times internally.
If you need to send information from an object, flatten the object before calling Appcues.identify(). For example, if you had a user property called "invoices" that was a collection of billing information, you could reduce that into the following useful properties:
<script>
var invoices = user.invoices || [];
var totalInvoices = invoices.length;
var lastInvoiceDate = (invoices[0] || {}).created_at;
Appcues.identify(user.id, {
name: user.name,
email: user.email,
totalInvoices: totalInvoices,
lastInvoiceDate: lastInvoiceDate
})
</script>Resetting User Session Data
While not necessary in most cases, it is possible to reset a user's session data by calling Appcues.reset(). This call 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 anonymous Appcues users, this can cause flows to show twice as it would reset the generated ID for that anonymous user.
Track Events
Tracking events in Appcues allows you to measure user engagement and interaction and target experiences based on those interactions, or lack thereof, and also see the impact of your Appcues experiences on user behaviors.
Whether you are installing on behalf of someone or working directly within your team, we encourage you to collaborate on and follow an Installation Plan to outline which events to track.
Note: Your implementation is incomplete if you do not track any events
Ways to Track Events
There are two ways to track events in Appcues. Whichever way(s) you choose to track, we recommend using descriptive names for clear understanding and easy selection in Studio.
Client-Side/Application Events via track()
Event tracking added directly into your product to notify Appcues of a successful event. This type of tracking is great for any verification or validation-based events as it only tracks on event completion.
Components of track()
-
Event Name (required) – Events are unique based on the
Event Name, so do not reuse names for different events.- Note: If you are installing Appcues on web and on a mobile app, event names must be different in each installation to be recognized as a web versus mobile event. Using the same name will result in the events being pooled together.
- Event Attributes (optional) – Provide extra context on the triggered event. Note: Event attributes are not visible in Studio or reporting, and can only be used with Event Triggering.
Example track() Call
- Without Attributes
Appcues.track("Event Name"); // e.g. "Clicked Some Button"- With Attributes
Appcues.track("Another Event", { // e.g. "Submitted a Help Ticket"
url: "/support",
article:"installation"
});Notes on Tracking Events via track()
- Ensure Appcues.identify() has been called on the page before tracking events
- Similar to user properties, Appcues only receives the events you explicitly track with Appcues. Meaning, you will need to add a track() call for each event
- If you use an analytics tool (e.g Mixpanel, Google Analytics, Heap, Hotjar, etc.), you can add an Appcues.track() call anywhere you’re already tracking events for that platform
Appcues.track()can be added within an event handler to track the event when the event functionality executes.
Click-to-Track Events via Appcues Builder
CTT Events do not require any code to track, and empower non-technical users to create, control and manage the different events within their UI that they want to target and track.
Check out our Click-to-Track doc for more information on how to create and use CTT events
Event Tracking will not backfill event data.
Looking to use historical data? You can send that information through our API!
Verify Your Installation
As you complete each section outlined above, Appcues recommends reviewing your installation progress for success of each component, then again once fully completed. To review and verify each step:
Add the Appcues SDK Script
Using the Appcues Debugger:
Identify Users and Groups
Track Events
Initial Installation Complete!
After completing the steps outlined above, your installation is completed!
It is recommended to review your installation periodically to ensure everything is up-to-date and your custom properties and events are supporting your use cases.
Other Considerations & Resources
User and Group IDs with Integrations
Some Appcues integrations have specific requirements to successfully connect to each other. In many cases, the Appcues User ID must exist as a value on the integration’s record/profile, keep this in mind when selecting which User ID to send to Appcues. A breakdown of some of Appcues common integrations’ requirements are below:
-
Salesforce
- Salesforce <> Appcues: The Appcues User ID must exist as a value on the Salesforce object (Contacts, Leads, etc.)
-
HubSpot
- HubSpot >> Appcues: The Appcues User ID must exist as a value on the HubSpot record.
- Appcues >> HubSpot: The HubSpot VID or corresponding email must exist as an Appcues user property (the email can be sent via identify, from the HubSpot>>Appcues sync, or from a data source connection)
-
Marketo
- Marketo >> Appcues: The Appcues User ID must exist as a value on the Marketo record.
- Appcues >> Marketo: The Marketo Lead ID or corresponding email must exist as an Appcues user property (the email can be sent via identify, from the Marketo>>Appcues sync, or from a data source connection).
-
Heap
- Heap >> Appcues: The Appcues User ID must exist as a value on the the Heap User Profile.
-
Amplitude
- Amplitude >> Appcues: The Appcues User ID must exist as a user property in Amplitude.
-
Mixpanel
- Mixpanel >> Appcues: The Appcues User ID must match the Distinct ID of the user in Mixpanel.
-
Hightouch
- Hightouch >> Appcues: The user Id on your Hightouch model must match the Appcues User ID sent in identify().
-
Census
- Census >> Appcues: The Sync Key on your Census model must match the Appcues User ID sent in identify().
Don't see your integration listed? Check out our docs for more supported integrations and to confirm requirements.
Reasons Why Appcues May Not Initialize or Load
While there are a variety of reasons this may happen, the most common reason is a Content Security Policy Violation – Appcues may be getting blocked by your site’s CSPs, thus resulting in failed initialization. To fix this, you can allow Appcues’ functionality and design to properly load. More information here.
Other Appcues Javascript Functionality
The Appcues SDK supports additional functionality to accomplish various use cases. More info here.
FAQ For Developers
Check out this doc for frequently asked questions when installing Appcues.
Having Issues Getting Installed?
Review the Troubleshooting doc for more information, or email us at support@appcues.com!