Skip to main content
The Userpilot JavaScript SDK allows you to identify users, track events, trigger content, and manage sessions directly from your web application.

​
Installation

npm i userpilot

import { Userpilot } from 'userpilot'

Userpilot.initialize(app_token, userpilotSettings);
Or include via CDN: 
<script>
	window.userpilotSettings = {token: app_token}
</script>
<script src="https://js.userpilot.io/sdk/latest.js"></script>

​
userpilotSettings Object

keyDescriptionExample
tokenAccount App TokenNX-98ii14b
versionPinned SDK Version1.730
ConnectionEnable longpolling modepolling | websocket
endpointAPI endpoint for when proxyingapi.example.com/socket
domainJS SDK domain for CNAMEjs.example.com
pageviewSpecifies what to collect from a URLpathonly | withhash | fullurl
auto_propsCollecting auto propertiestrue | false
sriSub Resource Integrity valuesha384-AivuiHqNxK7LKiAbFB+8god8cikUQmzAkyuJkIMleqa9QlGx1sUKFf6kzfskDqs7
auto_captureDefine autocapture privacy settingsSee Element Privacy Settings
callbacksListen to events that occur on the SDK sideSee Callbacks
integrations_interfacesDefine the integration interfaceSee Integrations Interfaces

​
Getting Started

To use the SDK, ensure it is loaded on your page. Then, you can call the available methods on the userpilot object.

​
Methods

​
identify(userId, [properties])

Identifies the current user with an ID and optional properties.
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. 
userpilot.identify("123", {
  name: "John",
  email: "[email protected]",
  created_at: "1519205055"
  // Additional user properties
});

​
anonymous()

Assigns a session-based unique ID for the current user on public pages. 
userpilot.anonymous();

​
reload([options])

Updates Userpilot content when the page state changes. 
userpilot.reload();
userpilot.reload({ url: 'https://example.com/hello' });

​
track(name, [properties])

Tracks a custom event for the current user. 
userpilot.track("invitedAgent", {
  name: "Sam",
  email: "[email protected]"
});

​
trigger(contentId)

Forces a specific Userpilot content to show for the current user. 
userpilot.trigger(17);

​
on(event, callback)

Registers a callback for a Userpilot event. 
userpilot.on('completed', function(event) {
  alert('Flow completed');
});

​
Event Examples

// Flow started
userpilot.on('started', (event) => { /* ... */ });

// Flow completed
userpilot.on('completed', (event) => { /* ... */ });

// Flow dismissed
userpilot.on('dismissed', (event) => { /* ... */ });

// Step interaction
userpilot.on('step', (event) => { /* ... */ });

​
off(event)

Removes a callback function attached to an event.

​
once(event, callback)

Registers a callback to be triggered only once.

​
end()

Ends the currently running flow.

​
clean()

Clears Userpilot storage and session data.

​
destroy()

Fully clears Userpilot storage and removes all active content.

​
suppress()

Fully stops Userpilot operations on the SDK side.

​
unsuppress()

Resumes SDK operations.

​
Parameters

MethodParametersDescription
identifyuserId, properties?Identify a user and set properties
anonymousAssign a session-based ID
reloadoptions?Reload Userpilot content
trackname, properties?Track a custom event
triggercontentIdShow specific content
onevent, callbackListen for Userpilot events
offeventRemove event listener
onceevent, callbackListen for event once
endEnd the current flow
cleanClear Userpilot storage
destroyRemove all Userpilot data and content