Skip to main content
There are three ways to install Userpilot: directly via JavaScript, which requires only a few minutes from an engineer; through Segment, if your web application already has it installed; or via Google Tag Manager (GTM), allowing you to install it yourself if GTM is already set up.
  • JavaScript
  • Segment
  • Google Tag Manager
1

Step 1: Install JavaScript Snippet

Copy the snippet and paste it at the beginning of your <head> section in your index.html file on every page you want to use Userpilot.Your App Token can be found under theenvironment tab .
<script>window.userpilotSettings = {token: "AppToken"};</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>
You can include the staging token on staging environments
2

Step 2: Identify Users

The user ID (a unique identifier) is required. Additional user and company properties can also be included in the script.
  • Multi-page Applications
The userpilot.identify() call is used on each page to identify the user and determine if they should see Userpilot content.
<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: "UNIQUE_COMPANY_ID", // 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>
  • Single page Applications
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.localStorage.get("token") is an example method of authentication.
React.useEffect(() => {
    if(isAuthenticated){
      Userpilot.identify('456987',{
        name: 'John Doe',
        email: 'john@site-domain.com',
        created_at: '2018-07-11',
      });
    }
  }, [isAuthenticated]);
3

Step 3: Reload Userpilot on Page Change

This step is only required for SPAs
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])
4

Step 4: Sending Tracked Events

Sending coded events to Userpilot is recommended to utilize the events in reports, in-app triggering, and segmenting users.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() 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("signed up");
//triggered when a user signs up. Helps track activation

userpilot.track("churned");
//triggered when a user cancels or becomes inactive. Useful for retention analysis

userpilot.track("plan upgraded", {
from_plan: “Starter”,
to_plan: “Growth”
});
//triggered when a user upgrades their plan. Helps track conversions and upsells

userpilot.track("payment completed", {
amount: “$500”,
invoice_number: “12345”
});
//triggered when a payment is completed. Useful for tracking revenue and billing success
For more advanced customizations and detailed API reference, check out our JavaScript SDK documentation.