Installation Overview (for Developers)
Table of Contents
A guide to installing Appcues for those who know how to code.
Before you get going, make sure you have an installation plan. The installation plan is meant as a reference for the data you'll send to Appcues from your installation. The recommended properties and events can get you started, but we highly recommend you (or the right person on your team!) review and fill out the installation plan template.
The following help articles will help with installation:
Background and set-up
- Use the step-by-step guide in the product for snippets tailored to your front-end stack. In order to go through the step-by-step installation guide, you will need access to your team's Appcues account.
- For a developer with knowledge of how their product tracks user properties and events, implementation requires an hour or more of work.
Add the Appcues SDK snippet
Place the following code snippet at the top of the document <head>. The Appcues ID can be found on the settings page in your account (a copy-able version of this snippet also exists in the step-by-step 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.
Notifying Appcues of page changes.
Appcues can automatically detect page changes. Note this is the default and no action is needed if you followed our installation guide after May 23, 2022. For details on notifying Appcues of page changes, see the instructions here.
Identify users and sending user properties
In order to target content to the right users at the right time, you need to identify users and send Appcues data about them.
Appcues implementation best practice:
Ensure that your Appcues.identify(); is called prior to the execution of the first page() call within your Appcues implementation code.
If not implemented this way, your end users could experience a delay due to events buffering while waiting on a user to be identified.
- Required: identify users with a unique ID. Appcues recommends choosing opaque and hard to guess user IDs, such as a UUID. See the FAQ for Developers for more details about how to choose a User ID.
- Recommended: pass in user properties (i.e. things like created date, user role, plan type, customer type, etc.). You do not have to pass in any PII.
- If you're installing for someone else and they filled out an installation plan, you can use it as a reference for what user properties to include. Make sure you include at least the properties included in the user property snippet in the installation guide.
Sample identify call:
Notes on formatting user properties
1. 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.
2. 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.
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.
3. 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.
If information in those objects are important, 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>Identify information about the user's account using “group”
Group properties describe the account on which the user is currently active; things like company name, plan tier, and industry. This information is optional and can be sent using Appcues.group(). 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.
Similar to Appcues.identify(), a unique group ID is required, and all the same formatting restrictions apply.
Example:
Appcues.group("6789", {
company_name: "Lendi Global",
plan_level: "enterprise",
employee_count: 12000,
in_trial: false
})Tracking events
Use the Appcues.track() call to track actions users take in your application.
Tracking events lets you target Appcues content based on actions people have or have not taken in your application, and also see the impact of your flow content on user behaviors.
If you're installing for someone else and they filled out an installation plan, you can use it as a reference for what events to include.
- Recommended: If you use an analytics tool (e.g Mixpanel, Google Analytics, Heap, Hotjar, etc.), add an Appcues.track() call anywhere you track events for that platform.
- Ensure Appcues.identify() or Appcues.anonymous() (or the analytics.js equivalent) has been called before tracking events.
Appcues.track("Event Name"); // e.g. "Clicked Some Button"
Appcues.track("Another Event", { // e.g. "Submitted a Help Ticket"
url: "/support",
article:"installation"
)};Note: Event tracking will not backfill event data. If users completed events before they were being tracked, we recommend identifying those users with a custom property.
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 the Anonymous call this can cause flows to show twice since it would wipe the generated ID for that anon guest.
Example:
Appcues.reset()Installing Appcues for anonymous users
While we do not recommend installing without an identify call, it is possible. See the guide on using anonymous users for more info.
Verify that everything is working.
Steps for verifying your installation are available on the "verify" step of the installation guide.
- The verification step will list out each domain in your application where Appcues has requested a script. If you want to use Appcues on a domain that you don't see listed there, make sure you have added the script to the appropriate page.
- To confirm that page tracking is working, open the Appcues debugger by appending ?hey_appcues to the URL of any page where Appcues is installed. Navigate around and confirm Appcues tracks each page change.
- To confirm that user identification is working and that user properties are being sent, confirm the "User identify" section is checked in the Appcues debugger. Expand the section to confirm that all properties are accurate.
- To confirm that events are being tracked, trigger one of the Appcues.track() calls you added and confirm it appears on the events page in Appcues.
Having issues getting installed?
Review the troubleshooting doc, or send us an email at support@appcues.com.