Installation Overview (for Developers)

Background and set-up

  • 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.
  • 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 can be completed in 10 minutes to an hour of work.

Add the Appcues SDK snippet

Place the following code snippet just after the opening  <body> tag. 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 src="//fast.appcues.com/YOUR_APPCUES_ID.js"></script>

Make sure to add the script on every page you want to use Appcues.

Re-initialize Appcues upon page changes.

Appcues relies on page changes to trigger content. If your application is a single page app (SPA), you'll need to use the appcues.page() call whenever the page changes. 

If your application is not a single page app, you may still will want to use the appcues.page() call if your application changes a large amount of content on a page with JavaScript.

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. 

  • Required: identify users with a unique ID.
  • Recommended: pass in user properties (i.e. things like email address, first name, last name, 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" could either be sent as a 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>

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"
)};

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. We'll help get you installed just right!