​
Introduction

Usertour.js is a lightweight client-side SDK that enables you to:
  • Identify and track users in your web application
  • Display interactive content (flows) to your users
  • Collect user behavior data for targeting
Follow us on Twitter for the latest updates and announcements.

​
Core Methods

Here are the most commonly used methods:
MethodDescription
usertour.init()Initialize the SDK with your Usertour.js Token
usertour.identify()Identify and track a user
usertour.group()Associate a user with a company/group

​
Installation

​
Recommended: NPM Installation

We recommend using the npm package for the best development experience: 
# Using npm
npm install usertour.js

# Or using Yarn
yarn add usertour.js
For alternative installation methods, see Usertour.js Installation Guide.
If you’re using a self-hosted UserTour instance, you’ll need additional configuration to connect Usertour.js to your own server. See our Self-Hosted Usertour.js Guide for detailed setup instructions.

​
Quick Start

Add this code to your application where you have access to user information: 
import usertour from 'usertour.js';

// Initialize with your Usertour.js Token
usertour.init('<USERTOUR_TOKEN>');

// Identify the current user
usertour.identify('<USER_ID>', {
  name: '<NAME>',
  email: '<EMAIL>',
  signed_up_at: '2023-06-14T16:25:49Z',
});

​
Important Notes

​
Replace Placeholders

  • Replace all placeholders (e.g., <USERTOUR_TOKEN>, <USER_ID>, <NAME>, <EMAIL>) with your actual values
  • The signed_up_at timestamp should be in ISO 8601 format

​
Getting Your Token

  • Find your Usertour.js Token in Settings -> Environments
  • Each environment (Production, Staging, etc.) has its own unique token
  • Make sure to use the correct token for your environment

​
How It Works

The npm package (usertour.js) is a thin wrapper around the real Usertour.js, which is loaded from our CDN. This design allows you to interact with the imported usertour object immediately. When you make your first method call, the real Usertour.js will be automatically loaded (asynchronously) and injected into the current page. All method calls are automatically queued by the usertour object until the SDK is ready. The core SDK is optimized for performance:
  • Small footprint (less than 16 KB gzipped)
  • Loads UI components only when needed
  • Supports both modern and legacy browsers
If you’ve installed Usertour.js via a <script> tag, you can access the object via window.usertour. However, be aware that it may not be immediately available, which is why we recommend using the npm package.

​
Attributes

The SDK provides a flexible attribute system for storing data about various entities like users, companies, and events. You can use this to store a user’s name, a company’s plan type, or decorate events with information like which billing plan was selected. These attributes can then be used within Usertour to segment users, personalize flows, or track behavior. When updating objects with attributes, you can use various data types:
TypeDescriptionExampleCommon Use
stringText values"John Doe"Names, emails
numberNumeric values42 or 1234.56Scores, metrics
booleanTrue/false valuestrue or falseFeature flags
datetimeISO 8601 timestamps"2023-06-14T16:25:49Z"Event times
listArrays of strings["tag1", "tag2"]Tags, categories
Here’s how to use attributes in your code: 
// Set user attributes
usertour.identify('123456', {
  name: 'John Doe',
  is_premium: true,
  subscription_tier: 'pro',
  last_login: '2023-06-14T16:25:49Z',
  tags: ['beta', 'early-adopter']
});

// Set company attributes
usertour.group('company_123', {
  name: 'Acme Corp',
  plan: 'enterprise',
  employee_count: 500,
  industry: 'technology'
});

// Remove an attribute by setting it to null
usertour.updateUser({
  phone_number: null
});
For best results, we recommend:
  • Using consistent naming conventions (lowercase with underscores)
  • Choosing appropriate data types for each attribute
  • Avoiding storage of sensitive information