Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
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 the Environment 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.
PII Data NoticeBefore passing any Personally Identifiable Information (PII) such as names, emails, or other sensitive user data to Userpilot:
  • Security & Compliance: Verify internally with your legal, security, and compliance teams that doing so aligns with your organization’s data privacy policies and applicable regulations (e.g., GDPR, CCPA).
  • Data Type Mapping: Ensure correct data type mapping for all properties. Userpilot supports String, Numeric, and Date types. Make sure dates are in ISO8601 format and numeric values are properly formatted. Incorrect type mapping can cause issues with segmentation, analytics, and debugging.
  • Debugging: Proper data formatting is crucial for effective debugging and troubleshooting. Verify that your data maps correctly to Userpilot’s expected formats before implementation.
  • 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.
import { useLocation } from "react-router-dom";

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.

​
Prerequisites

  • Access to your web application’s codebase (for JavaScript) or GTM/Segment account
  • Your Userpilot App Token from Settings > Environment
  • User authentication system to provide unique user IDs

​
Expected Result

After successful installation:
  • Userpilot SDK loads on your pages (check for window.userpilot in console)
  • Users appear in People after identify() is called
  • You can create and display flows to identified users

​
Common Issues

SymptomCauseSolution
userpilot is not definedSDK not loadedVerify script is in <head>, check for CSP blocks
Content not showingUser not identifiedEnsure identify() is called before content triggers
SPA navigation issuesMissing reload()Call userpilot.reload() on every route change
Ad blocker interferenceThird-party domain blockedConsider custom domain hosting