Install Userpilot on Your Web App

In order to trigger Experiences live on your app, you must install the Userpilot script on your product or site.

Installing Userpilot on your web app is very easy, and will only take a few minutes to do so.

All you have to do is follow the steps below.

Single-Page Applications

Step1: Install JavaScript Snippet

Using SDK

Copy the snippet below and paste it at the beginning of your <head> section in your index.html file on every page you want to use Userpilot.

<script>window.userpilotSettings = {token: "87jh57"};</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>

Using Node Package Manager

First, install the package using NPM:

NPM | Userpilot

Then place the code below in your main entry point file.

import { Userpilot } from 'userpilot'
// Initialize Userpilot
Userpilot.initialize('87jh57')

Your App Token can be found under the environment tab.

Step 2: Identify Users

To send Userpilot information about the current user, you must call Userpilot's identify function and pass the user's attributes inside it. Userpilot will then be able to create sessions for that user and track them. You only have to call this function once, upon a successful user authentication.

The following is an example of how Userpilot's identify function is called in the app's entry point only when the user is successfully authenticated.

React.useEffect(() => {
    if(isAuthenticated){
      Userpilot.identify('456987',{
        name: 'John Doe',
        email: 'john@site-domain.com',
        created_at: '2018-07-11',
      });
    }
  }, [isAuthenticated]);

Note: localStorage.get("token") is an example method of authentication.

Step 3: Reload Userpilot on Page Change

Userpilot must be reloaded on every route change through Userpilot's reload function. In the following example, we call the reload function in the route change watcher file (in our case it is auth.guard.ts).

The following is an example of how Userpilot's identify function is called in the app's entry point only when the user is successfully authenticated.

const location = useLocation();

React.useEffect(() => {
  if(isAuthenticated){
    Userpilot.reload();
  }
}, [location])

Note: If you want to trigger experiences on anonymous users, call userpilot.reload() without checking for authentication on every page change.

Step 4: Tracked Events

Use the userpilot.track(); call to track actions users take in your application.

If you use an analytics tool (e.g. Mixpanel, Amplitude, Hotjar, FullStory, Google Analytics) add theuserpilot.track(); method wherever you’re already tracking events. You can also pass extra metadata alongside the event's name to pass unique information about the event.

userpilot.track("Event Name");
// e.g. Clicked the purchase button
userpilot.track("Clicked purchase button");
// e.g. Submitted a help ticket
userpilot.track("Submitted help ticket", {
  url: "/support",
  article: "installation"
});

Multi-Page Applications

Step 1: Install JavaScript Snippet

Copy the snippet below and paste it at the beginning of your <head> section in your index.html file on every page you want to use Userpilot.

<script>window.userpilotSettings = {token: "87jh57"};</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>

Step 2: Identify Users

The userpilot.identify() call is used on each page to identify the user and determine if they should see Userpilot content. The user ID (a unique identifier) is required. Additional propertiescan also be included.

<script>
  userpilot.identify( "UNIQUE USER ID", // Used to identify users
    {
      name: "John Doe", // Full name
      email: "customer@example.com", // Email address
      created_at: '2019-10-17' // ISO8601 Date
    company: {
      id: 1, // Required, used to identify the company
      name: "Acme Labs",
      created_at: '2019-10-17' // ISO8601 Date
    },
      // Additional properties
      // projectId: "1",
      // trialEnds: '2019-10-31' // ISO8601 Date
    }
  );
</script>

Identify Anonymous Users

If users are anonymous (no authentication is involved) and therefore do not have ids then use Userpilot's anonymous function to identify the user instead of identify.

userpilot.anonymous();

Note: If you're installing Userpilot for someone, make sure you ask them what user properties and events they need. If they filled out a template you can use it as a reference.

Step 3: Tracked events

Use the userpilot.track(); call to track actions users take in your application.

userpilot.track("Event Name");
// e.g. Clicked the purchase button
userpilot.track("Clicked purchase button");
// e.g. Submitted a help ticket
userpilot.track("Submitted help ticket", {
  url: "/support",
  article: "installation"
});

It is recommended to limit the total number of unique event names and using metadata to provide additional context for each event. Ensure that the combined size of all of your unique event names does not exceed 512 KB.