JavaScript SDK

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

key	Description	Example
token	Account App Token	NX-98ii14b
version	Pinned SDK Version	1.730
connection	Enable long-polling mode	polling \| websocket
endpoint	API endpoint for when proxying	api.example.com/socket
domain	JS SDK domain for CNAME	js.example.com
pageview	Specifies what to collect from a URL	pathonly \| withhash \| fullurl
auto_props	Collecting auto properties	true \| false
sri	Sub Resource Integrity value	sha384-AivuiHqNxK7LKiAbFB+8god8cikUQmz
auto_capture	Define autocapture privacy settings	See Element Privacy Settings
crossSubdomainSessionCookie	Keep sessions and active flows across subdomains (disabled by default)	`true`
callbacks	Listen to events that occur on the SDK side	See Callbacks
integrations_interfaces	Define the integration interface	See Integrations Interfaces

Keep sessions and active flows across subdomains

Set crossSubdomainSessionCookie to true to keep a user’s session and in-progress flow when they move between subdomains. The SDK stores the session ID and flow progress in first-party cookies for the same user and session. This option defaults to false and has no effect when disableCookies is true.

window.userpilotSettings = {
  token: "YOUR_APP_TOKEN",
  crossSubdomainSessionCookie: true
};

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, )

Identifies the current user with an ID and optional properties.

userpilot.identify("123", {
  name: "John",
  email: "john@example.com",
  created_at: "1519205055"
  // Additional user properties
});

anonymous()

Assigns a session-based unique ID for the current user on public pages.

userpilot.anonymous();

reload()

Updates Userpilot content when the page state changes.

userpilot.reload();
userpilot.reload({ url: 'https://example.com/hello' });

track(name, )

Tracks a custom event for the current user.

userpilot.track("invitedAgent", {
  name: "Sam",
  email: "sam@example.com"
});

triggerById(contentId)

Forces specific Userpilot content to show for the current user.

userpilot.triggerById(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()

End 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

Method	Parameters	Description
identify	userId, properties?	Identify a user and set properties
anonymous		Unique session-based ID
reload	options?	Reload Userpilot content
track	name, properties?	Track a custom event
triggerById	contentId	Show specific content
on	event, callback	Listen for Userpilot events
off	event	Remove event listener
once	event, callback	Listen for event once
end		End the current flow
clean		Clear Userpilot storage
destroy		Remove all Userpilot data and content
suppress		Stop Userpilot operations on the SDK
unsuppress		Resume Userpilot after suppression

Installation

Security

Data sync

Advanced

Installation

userpilotSettings Object

Keep sessions and active flows across subdomains

Getting Started

Methods

identify(userId, )

anonymous()

reload()

track(name, )

triggerById(contentId)

on(event, callback)

Event Examples

off(event)

once(event, callback)

end()

clean()

destroy()

suppress()

unsuppress()

Parameters

​Installation

​userpilotSettings Object

​Keep sessions and active flows across subdomains

​Getting Started

​Methods

​identify(userId, )

​anonymous()

​reload()

​track(name, )

​triggerById(contentId)

​on(event, callback)

​Event Examples

​off(event)

​once(event, callback)

​end()

​clean()

​destroy()

​suppress()

​unsuppress()

​Parameters

Installation

userpilotSettings Object

Keep sessions and active flows across subdomains

Getting Started

Methods

identify(userId, )

anonymous()

reload()

track(name, )

triggerById(contentId)

on(event, callback)

Event Examples

off(event)

once(event, callback)

end()

clean()

destroy()

suppress()

unsuppress()

Parameters