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
Complete an Installation Plan to outline your tailored installation components
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).
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 your identify() 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 each identify(). Because of this, anything that is immediately relevant to the user should be sent directly via identify().
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.
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
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:
Confirm that Installed and Connected to Appcues are green The Appcues Debugger will not open if Appcues is not installed/detected. If you’ve confirmed that the Appcues SDK has been added, but the Debugger does not open, it may be due to various reasons which can be investigated in your browser’s console. More information can be found in the Other Considerations section below.
Confirm that Tracking Pages is green To confirm page tracking, navigate across your product with the Debugger open. As the URLs change, the Tracking Pages indicator should self-resolve to green. It may flash red while the new page finishes loading – this is fine so long as status updates to greenwithout refreshing the page.
Identify Users and Groups
Confirm that the User ID and any custom user properties are properly reflected in the User Identified section, and the Group ID and any custom group properties within the Group Identified section of the Debugger Custom user and group properties can be seen by expanding the User Identified and Group Identified details and scrolling through the listed properties. Appcues auto-properties are listed first and are recognizable with their starting underscore (_appcuesId), then custom properties listed after that
Only custom properties sent via identify() and group() will be visible in the Debugger. Properties sent via an integration will only be visible in Studio and can be confirmed in your Custom Properties tab for user properties, and an account's Properties page for group properties.
Track Events
For Appcues.track() Events – trigger the event(s) in the installed environment and confirm that it appears on your Events page (labeled as Application Event imported with SDK), and/or within your Events Explorer with the Event Source set to “Application Events”. Note: Buttons within flows that have been tracked as an event will also appear as an Application Event
For Click-to-Track (CTT) Events – When creating a CTT in the Appcues Builder, there is a “Test” button to test that event without completely triggering it. To fully trigger it, save the CTT then interact with it outside of the Builder. These events will be visible on your Events page (labeled as Track Event (Builder) created in Builder), and if they have not yet been triggered outside the Builder the Last Seen will show “Not Seen Yet”. CTT Events can also be seen within Events Explorer when Event Source is set to “Track Events (Builder)”
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:
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 >> 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).
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 Implementation@Appcues.com!