> ## 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.

# JavaScript SDK

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

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

***

## Installation

```bash theme={null}
npm i userpilot
```

```javascript theme={null}
import { Userpilot } from 'userpilot'

Userpilot.initialize(app_token, userpilotSettings);
```

Or include via CDN:

```html theme={null}
<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 longpolling 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+8god8cikUQmzAkyuJkIMleqa9QlGx1sUKFf6kzfskDqs7                     |
| auto\_capture            | Define autocapture privacy settings         | See [Element Privacy Settings](/developer/installation/sdk/settings/privacy)                |
| callbacks                | Listen to events that occur on the SDK side | See [Callbacks](/developer/installation/sdk/settings/callbacks)                             |
| integrations\_interfaces | Define the integration interface            | See [Integrations Interfaces](/developer/installation/sdk/settings/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.

<Warning>
  **PII Data Notice**

  Before 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.
</Warning>

```javascript theme={null}
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.

```javascript theme={null}
userpilot.anonymous();
```

***

### **reload(\{options})**

Updates Userpilot content when the page state changes.

```javascript theme={null}
userpilot.reload();
userpilot.reload({ url: 'https://example.com/hello' });
```

***

### **track(name, \{properties})**

Tracks a custom event for the current user.

```javascript theme={null}
userpilot.track("invitedAgent", {
  name: "Sam",
  email: "sam@example.com"
});
```

***

### **trigger(contentId)**

Forces a specific Userpilot content to show for the current user.

```javascript theme={null}
userpilot.trigger(17);
```

***

### **on(event, callback)**

Registers a callback for a Userpilot event.

```javascript theme={null}
userpilot.on('completed', function(event) {
  alert('Flow completed');
});
```

#### Event Examples

```javascript theme={null}
// 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

| Method    | Parameters          | Description                           |
| --------- | ------------------- | ------------------------------------- |
| identify  | userId, properties? | Identify a user and set properties    |
| anonymous |                     | Assign a session-based ID             |
| reload    | options?            | Reload Userpilot content              |
| track     | name, properties?   | Track a custom event                  |
| trigger   | 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 |

***

<Frame>
  [**For any questions or concerns, please reach out to support@userpilot.com**](mailto:support@userpilot.com)
</Frame>