Usertour IO

https://docs.usertour.io
Admin
Documentation repository created by Site2MD.
Tokens:72,131
Snippets:1,046
Trust Score:7.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic Usage of start()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/start

This snippet shows the basic usage of the start() method to display Usertour content using its unique ID.

```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5');
```

--------------------------------

### Navigate Action Example

Source: https://docs.usertour.io/api-reference-v2/conditions-and-actions

Example of a button configuration using the navigate action to open a URL in a new tab.

```json
{ "type": "button", "text": "See pricing", "actions": [{ "type": "navigate", "url": "/pricing", "newTab": true }] }
```

--------------------------------

### Example Flows

Source: https://docs.usertour.io/use-cases/close-button-follow-up

Illustrates the content of an original onboarding flow and a subsequent follow-up tooltip.

```text
Original flow:
Welcome onboarding

Follow-up flow:
You can restart onboarding from the help menu at any time.
```

--------------------------------

### Install Project Dependencies

Source: https://docs.usertour.io/open-source/local-development

Install all necessary project dependencies using pnpm. This command should be run from the root of the cloned repository.

```bash
pnpm install
```

--------------------------------

### Start Usertour Development Servers

Source: https://docs.usertour.io/open-source/local-development

Start the backend API server, the frontend web application, and the SDK development server independently. The web application will be accessible at http://localhost:5174.

```bash
# Start the backend API server
pnpm dev:server

# Start the web application
pnpm dev:web

# Start the SDK development server
pnpm dev:sdk
```

--------------------------------

### Resume Previous Session with start()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/start

Use the 'continue' option set to true with the start() method to allow users to resume Usertour content from where they left off in their last session.

```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5', {
  continue: true
});
```

--------------------------------

### Start Usertour with Docker Compose

Source: https://docs.usertour.io/open-source/self-hosting

Command to start Usertour using Docker Compose. Ensure you are in the directory with your docker-compose.yml file.

```bash
docker-compose -f docker-compose.yml up -d
```

```bash
docker compose -f docker-compose.yml up -d
```

--------------------------------

### Install Usertour.js via NPM or Yarn

Source: https://docs.usertour.io/developers/usertourjs-reference/overview

Install the Usertour.js package using npm or Yarn for the recommended development experience.

```bash
# Using npm
npm install usertour.js

# Or using Yarn
yarn add usertour.js
```

--------------------------------

### Install Usertour MCP plugin

Source: https://docs.usertour.io/build-onboarding-with-ai

Commands to add and install the Usertour skills plugin for Claude Code.

```text
/plugin marketplace add usertour/skills
/plugin install usertour@usertour
```

--------------------------------

### Install Usertour.js via NPM

Source: https://docs.usertour.io/developers/usertourjs-reference/installation

Use this command to install the usertour.js npm package. This is recommended for modern web applications using module bundlers.

```bash
npm install usertour.js
```

--------------------------------

### Banner Configuration Example

Source: https://docs.usertour.io/api-reference-v2/type-data

Defines a banner with text content and specific behavior settings.

```json
{
  "content": [{ "type": "text", "markdown": "🎉 New feature live!" }],
  "settings": { "stickToTop": true, "allowDismiss": true }
}
```

--------------------------------

### Usertour Company Group Setup

Source: https://docs.usertour.io/how-to-guides/companies

Use this snippet to group users into a company, optionally providing company and membership attributes. Ensure Usertour.js is installed before use.

```javascript
usertour.group(companyId, {
  // Optional company attributes
  name: "Acme Corp",
  plan: "enterprise",
  // Optional membership attributes
  role: "admin"
});
```

--------------------------------

### Start Flow From Beginning

Source: https://docs.usertour.io/use-cases/restart-onboarding-from-button

Use `usertour.start()` without additional options to restart an onboarding flow from its initial step. This is suitable for a standard replay button.

```javascript
usertour.start("your_flow_id");
```

--------------------------------

### Show Content Only Once with start()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/start

Configure the start() method to display content only to users who haven't seen it before by setting the 'once' option to true. The 'continue' option is ignored when 'once' is true.

```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5', {
  once: true
});
```

--------------------------------

### Example Scenario Steps

Source: https://docs.usertour.io/use-cases/continue-after-text-input

Illustrates a two-step scenario where the first step prompts for user input and the second step relates to that input.

```text
Step 1:
Tell us about your setup.

Step 2:
Select this checkbox if you want to enable the option.
```

--------------------------------

### start()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/start

Programmatically trigger and display Usertour content for authenticated users. This method allows for custom triggers for onboarding and feature discovery flows.

```APIDOC
## start(contentId, options)

### Description
Programmatically trigger and display Usertour content (such as flows, checklists, or other interactive guides) for your authenticated users. When called, the specified content will be rendered immediately in your application.

### Method
`start`

### Parameters
#### Path Parameters
- **contentId** (string) - Required - The unique identifier of the content you want to display. You can find this ID in the content detail page URL: `/env/{envId}/{contentType}/{contentId}/detail`

#### Query Parameters
- **options** (object) - Optional - Configuration object to customize the content display behavior.
  - **once** (boolean) - Optional - When set to true, the content will only be shown to users who haven't seen it before. If the user has already viewed the content, nothing will happen. Defaults to false.
  - **continue** (boolean) - Optional - When set to true, the content will resume from where the user left off in their previous session. If false, the content will start from the beginning. Defaults to false.

### Note
When `once: true` is set, the `continue` option will not take effect since the content will only be shown once to the user.

### Return
Returns a `Promise` that resolves when the content has been successfully initialized and displayed.

### Example
#### Basic Usage
```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5');
```

#### Show Content Only Once
```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5', {
  once: true
});
```

#### Resume Previous Session
```javascript
usertour.start('cmaw8v1ch013s147h0uw8aha5', {
  continue: true
});
```

### Note
Make sure to call `init()` before using any other Usertour.js methods
```

--------------------------------

### Configure a launcher with icon style

Source: https://docs.usertour.io/api-reference-v2/type-data

Example configuration for a launcher using an icon style anchored to a specific data selector with a tooltip.

```json
{
  "style": "icon",
  "target": { "selector": "[data-tour='help']" },
  "tooltip": { "content": [{ "type": "text", "markdown": "Need help? Start here." }] }
}
```

--------------------------------

### isStarted()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/is-started

Checks if a specific Usertour content (flow or checklist) has been started. Returns true if started, false otherwise.

```APIDOC
## isStarted()

### Description
Checks if a specific Usertour content has been started. Currently supports checking the status of flows and checklists. Returns a boolean value indicating the content's start status.

### Parameters
#### Path Parameters
- **contentId** (string) - Required - The unique identifier of the content. You can find this ID in the content detail page URL: `/env/{envId}/{contentType}/{contentId}/detail`

### Return
`boolean` - Returns `true` if the content has been started, `false` if it hasn't been started yet.

### Example
#### Basic Usage
```javascript
const isContentStarted = usertour.isStarted('cmaw8v1ch013s147h0uw8aha5');
if (isContentStarted) {
  console.log('Content has been started');
} else {
  console.log('Content has not been started yet');
}
```

<Note>
  Make sure to call `init()` before using any other Usertour.js methods
</Note>
```

--------------------------------

### Resource Center Configuration Example

Source: https://docs.usertour.io/api-reference-v2/type-data

Defines a resource center with a header and a tab containing richtext and content-list blocks.

```json
{
  "headerText": "Help & resources",
  "tabs": [
    {
      "name": "Guides",
      "blocks": [
        { "type": "richtext", "content": [{ "type": "text", "markdown": "## Getting started" }] },
        { "type": "content-list", "name": "Tours", "items": [{ "content": "cm9f6vwed0002iejc4vg2zu3t", "contentType": "flow" }] }
      ]
    }
  ]
}
```

--------------------------------

### Configure Environment Variables

Source: https://docs.usertour.io/open-source/local-development

Copy example environment files and configure them for the web application, API server, and SDK. Update database and cache settings for the API server.

```bash
# Web application
cp apps/web/.env.example apps/web/.env

# API server
cp apps/server/.env.example apps/server/.env
# Update Redis and PostgreSQL configuration in apps/server/.env

# SDK
cp apps/sdk/.env.example apps/sdk/.env
```

--------------------------------

### Announcement Feed Configuration Example

Source: https://docs.usertour.io/api-reference-v2/type-data

Defines an announcement with a title, introductory content, and badge distribution.

```json
{
  "title": "Dark mode is here",
  "introContent": [{ "type": "text", "markdown": "Flip it on in **Settings → Appearance**." }],
  "distribution": "badge"
}
```

--------------------------------

### Install Chrome DevTools MCP plugin

Source: https://docs.usertour.io/build-onboarding-with-ai

Commands to add and install the Chrome DevTools plugin to assist the AI with element selection and verification.

```text
/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-plugins
```

--------------------------------

### Tracker Configuration Example

Source: https://docs.usertour.io/api-reference-v2/type-data

Defines a tracker object that records a specific event code.

```json
{ "event": "activated" }
```

--------------------------------

### Condition Grouping Example

Source: https://docs.usertour.io/api-reference-v2/conditions-and-actions

Demonstrates a condition list using an OR group to match multiple URL paths.

```json
[
  { "type": "segment", "segment": "cm9f6vwed0002iejc4vg2zu3t", "in": true },
  { "type": "group", "match": "any", "conditions": [
    { "type": "current_url", "includes": ["/pricing"] },
    { "type": "current_url", "includes": ["/billing"] }
  ]}
]
```

--------------------------------

### Check if Content is Started

Source: https://docs.usertour.io/developers/usertourjs-reference/content/is-started

Use this snippet to determine if a specific Usertour flow or checklist has been started by the user. Ensure Usertour.js has been initialized with `init()` before calling this method.

```javascript
const isContentStarted = usertour.isStarted('cmaw8v1ch013s147h0uw8aha5');
if (isContentStarted) {
  console.log('Content has been started');
} else {
  console.log('Content has not been started yet');
}
```

--------------------------------

### Example Repository URL for Coolify

Source: https://docs.usertour.io/open-source/coolify-deployment

Use this repository URL when configuring your deployment in Coolify. It's recommended to clone this to your own repository for better control.

```text
https://github.com/usertour/examples
```

--------------------------------

### Initialize and Identify User with Usertour.js (NPM)

Source: https://docs.usertour.io/developers/usertourjs-reference/installation

Import and initialize the Usertour SDK with your environment token, then identify the current user with their attributes. This snippet is used after installing via NPM.

```javascript
import usertour from 'usertour.js';

// Initialize the Usertour SDK with your environment token
usertour.init('USERTOUR_TOKEN');

// Identify the current user with their attributes
usertour.identify('USER_ID', {
  name: 'USER_NAME',
  email: 'USER_EMAIL',
  signed_up_at: 'USER_SIGNED_UP_AT',
});
```

--------------------------------

### Rule Configuration JSON

Source: https://docs.usertour.io/api-reference-v2/rules

Example of a rule configuration object defining URL conditions, frequency mode, and priority.

```json
{
  "when": [{ "type": "current_url", "includes": ["/dashboard"] }],
  "frequency": { "mode": "once" },
  "priority": "medium"
}
```

--------------------------------

### Local Development Environment Variables

Source: https://docs.usertour.io/open-source/self-hosting

Configure these environment variables in your .env file for the local development setup.

```env
# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASS=

# PostgreSQL Configuration
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/usertour?schema=usertour&sslmode=prefer
```

--------------------------------

### URL Path Example

Source: https://docs.usertour.io/how-to-guides/urls

Illustrates the path component of a URL. The path is the part after the domain and before query parameters or fragments.

```html
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                  \
                           |
                          path
```

--------------------------------

### Define a button block

Source: https://docs.usertour.io/api-reference-v2/blocks

Example of a button block configuration. Requires both text and at least one action to be publishable.

```json
{
  "type": "button",
  "text": "Next",
  "variant": "primary",
  "actions": [{ "type": "goto_step", "step": "pricing" }]
}
```

--------------------------------

### Simple Tour Button Actions

Source: https://docs.usertour.io/use-cases/choose-between-two-tours

Configure the 'Simple tour' button to dismiss the current chooser flow and start the 'Simple tour' flow.

```text
Dismiss flow
Start new flow/checklist: Simple tour
```

--------------------------------

### Install Usertour.js via HTML Snippet

Source: https://docs.usertour.io/developers/usertourjs-reference/installation

Add this script to your HTML file just before the closing </body> tag for traditional web applications or Google Tag Manager integration.

```html
!function(){var e="undefined"==typeof window?{}:window,r=e.usertour;if(!r){var t="https://js.usertour.io/",n=null;r=e.usertour={_stubbed:!0,load:function(){return n||(n=new Promise((function(r,o){var s=document.createElement("script");s.async=!0;var i=e.USERTOURJS_ENV_VARS||{};"es2020"===(i.USERTOURJS_BROWSER_TARGET||function(e){for(var r=[[/Edg\/|,Edg\/(\d+)/,80],[/OPR\/|,OPR\/(\d+)/,67],[/Chrome\/|,Chrome\/(\d+)/,80],[/CriOS\/|,CriOS\/(\d+)/,100],[/Safari\/|,Version\/(\d+)/,14],[/Firefox\/|,Firefox\/(\d+)/,74]],t=0;t<r.length;t++){var n=r[t],o=n[0],s=n[1],i=n[2];if(e.match(o)){var u=e.match(new RegExp(s));if(u&&parseInt(u[1],10)>=i)return"es2020";break}}return"legacy"}(navigator.userAgent))?(s.type="module",s.src=i.USERTOURJS_ES2020_URL||t+"es2020/usertour.js"):(s.src=i.USERTOURJS_LEGACY_URL||t+"legacy/usertour.iife.js"),s.onload=function(){r()},s.onerror=function(){document.head.removeChild(s),n=null;var e=new Error("Could not load Usertour.js");console.warn(e.message),o(e)},document.head.appendChild(s)}))),n}};var o=e.USERTOURJS_QUEUE=e.USERTOURJS_QUEUE||[],s=function(e){r[e]=function(){var t=Array.prototype.slice.call(arguments);r.load(),o.push([e,null,t])}},i=function(e){r[e]=function(){var t,n=Array.prototype.slice.call(arguments);r.load();var s=new Promise((function(e,r){t={resolve:e,reject:r}}));return o.push([e,t,n]),s}},u=function(e,t){r[e]=function(){return t}};s("disableEvalJs"),s("init"),s("off"),s("on"),s("registerCustomInput"),s("reset"),s("setBaseZIndex"),s("setSessionTimeout"),s("setTargetMissingSeconds"),s("setCustomInputSelector"),s("setCustomNavigate"),s("setCustomScrollIntoView"),s("setInferenceAttributeFilter"),s("setInferenceAttributeNames"),s("setInferenceClassNameFilter"),s("setScrollPadding"),s("setServerEndpoint"),s("setShadowDomEnabled"),s("setPageTrackingDisabled"),s("setUrlFilter"),s("setLinkUrlDecorator"),s("openResourceCenter"),s("closeResourceCenter"),s("toggleResourceCenter"),s("showResourceCenterLauncher"),s("hideResourceCenterLauncher"),i("endAll"),i("group"),i("identify"),i("identifyAnonymous"),i("start"),i("track"),i("updateGroup"),i("updateUser"),u("isIdentified",!1),u("isResourceCenterOpen",!1),u("isStarted",!1)}}();

// Initialize the Usertour SDK with your environment token
usertour.init('USERTOUR_TOKEN');

// Identify the current user with their attributes
usertour.identify('USER_ID', {
  name: 'USER_NAME',
  email: 'USER_EMAIL',
  signed_up_at: 'USER_SIGNED_UP_AT',
});
```

--------------------------------

### Cursor MCP Configuration

Source: https://docs.usertour.io/api-reference-v2/mcp

Manual configuration for Cursor by adding the server to the mcp.json file or installing authoring skills.

```json
{
  "mcpServers": {
    "usertour": {
      "url": "https://mcp.usertour.io/mcp"
    }
  }
}
```

```bash
npx skills add https://github.com/usertour/skills
```

--------------------------------

### Start Flow via URL

Source: https://docs.usertour.io/how-to-guides/starting-flows

Initiate a flow or checklist by constructing a URL with the flow ID. This is useful for creating links or buttons that trigger specific tours.

```text
https://www.usertour.io/flows/?usertour=your_flow_id
```

```text
https://www.usertour.io/flows/?usertour=cmaw8v1ch013s147h0uw8aha5
```

--------------------------------

### PATCH /versions/{id}

Source: https://docs.usertour.io/api-reference-v2/rules

Updates the start rules for a specific content version.

```APIDOC
## PATCH /versions/{id}

### Description
Updates the start rules for a content version. Use this to define when content auto-starts, how often it shows, and its priority.

### Method
PATCH

### Endpoint
/versions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the version.

#### Request Body
- **startRules** (object) - Optional - The configuration for auto-starting content.
  - **when** (array) - Optional - Conditions that must match for the content to auto-start.
  - **frequency** (object) - Optional - How often the content may show.
  - **priority** (string) - Optional - Ordering priority (highest, high, medium, low, lowest).
  - **waitSeconds** (number) - Optional - Delay in seconds before content becomes eligible.
  - **startIfNotComplete** (boolean) - Optional - Only start if the user has not completed the content.
```

--------------------------------

### Query Parameter Matching

Source: https://docs.usertour.io/how-to-guides/urls

Illustrates matching query parameters. Shows how to match specific values, values starting with certain text, or any value using wildcards.

```js
// 1. Match values starting with specific text:
// ?param=a* matches:
// - ?param=apple
// - ?param=admin
// // But won't match:
// - ?param=banana (doesn't start with 'a')
// - ?param (no value)
// - ?param2=apple (wrong parameter name)

// 2. Match any value:
// ?param=* matches:
// - ?param=anything
// - ?param (empty value is OK)
// // But won't match:
// - ?param2=value (wrong parameter)

```

--------------------------------

### Define an image block

Source: https://docs.usertour.io/api-reference-v2/blocks

Example of an image block configuration including URL, alt text, width, and link properties.

```json
{
  "type": "image",
  "url": "https://example.com/logo.png",
  "alt": "Logo",
  "width": { "unit": "percent", "value": 80 },
  "link": { "url": "https://example.com", "newTab": true }
}
```

--------------------------------

### Create a one-step video modal flow with Usertour MCP

Source: https://docs.usertour.io/build-onboarding-with-ai

A prompt example for the Usertour MCP to generate a modal containing a specific YouTube video, supporting copy, and a call-to-action, saved as a draft.

```text
Use the Usertour MCP to create a one-step modal flow featuring this
YouTube video:

https://www.youtube.com/watch?v=ZIaOBAjvc38

Use the title:

**Sam Altman: "Never a Better Time to Do a Startup"**

Add concise supporting copy explaining why this is a uniquely promising
time to build a startup and what viewers can learn from the video.
Include a clear watch action and an easy way to close the modal.

Match the product's visual style, verify that the video embed works
correctly, and save the flow as a draft.
```

--------------------------------

### URL Query Example

Source: https://docs.usertour.io/how-to-guides/urls

Highlights the query component of a URL. The query follows the path and is separated by '?', containing key-value pairs.

```html
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                                      \___________/
                                            |
                                          query
```

--------------------------------

### Text Block Example

Source: https://docs.usertour.io/api-reference-v2/blocks

A rich-text paragraph block supporting markdown and user attribute interpolation.

```json
{ "type": "text", "markdown": "Welcome **{{ first_name | default: \"there\" }}** 👋" }
```

--------------------------------

### Usertour Initialization and Identification

Source: https://docs.usertour.io/use-cases/restart-onboarding-from-button

Before calling `usertour.start()`, ensure Usertour is initialized with your token and the current user is identified. This setup is typically done after your application's main loading sequence.

```javascript
usertour.init("your_token");
usertour.identify("user_id");
```

--------------------------------

### Toggle Resource Center with a Help Button

Source: https://docs.usertour.io/how-to-guides/resource-center

Integrate your own 'Help' button to toggle the Resource Center panel. This example assumes a 'helpButton' element and the Usertour.js library are available.

```javascript
helpButton.addEventListener('click', () => {
  usertour.toggleResourceCenter();
});
```

--------------------------------

### Checklist data structure example

Source: https://docs.usertour.io/api-reference-v2/type-data

Defines a checklist with an initial expanded state and two items, each using different completion triggers.

```json
{
  "buttonText": "Get started",
  "initialDisplay": "expanded",
  "items": [
    { "name": "Create your first project", "clickActions": [{ "type": "navigate", "url": "/projects/new" }], "completeWhen": [{ "type": "task_clicked" }] },
    { "name": "Invite a teammate", "completeWhen": [{ "type": "event", "event": "member_invited" }] }
  ]
}
```

--------------------------------

### Production Setup Docker Compose Configuration

Source: https://docs.usertour.io/open-source/self-hosting

Simplified Docker Compose configuration for production. Assumes Redis and PostgreSQL are managed externally.

```yaml
services:
  app:
    image: usertour/usertour:latest
    ports:
      - "8011:80"
    env_file:
      - .env
    restart: always
```

--------------------------------

### Open Resource Center on Button Click

Source: https://docs.usertour.io/developers/usertourjs-reference/resource-center/open-resource-center

This snippet demonstrates how to open the Usertour.js resource center when a custom help button is clicked. Ensure that `usertour.js` is initialized before calling this method. This example requires a `helpButton` element to be present in the DOM.

```javascript
// Open the resource center when the user clicks a custom help button
helpButton.addEventListener('click', () => {
  usertour.openResourceCenter();
});
```

--------------------------------

### Define a step trigger

Source: https://docs.usertour.io/api-reference-v2/rules

Example of a trigger configuration that advances to the next step when a specific modal element becomes present.

```json
{
  "when": [{ "type": "element", "target": { "selector": "#welcome-modal" }, "state": "present" }],
  "do": [{ "type": "goto_step", "step": "step-2" }]
}
```

--------------------------------

### Embed Block JSON Structure

Source: https://docs.usertour.io/api-reference-v2/blocks

Example of an embed block configuration using a YouTube URL and percentage-based width.

```json
{ "type": "embed", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "width": { "unit": "percent", "value": 100 } }
```

--------------------------------

### React Router v5 (Legacy) History Setup

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/set-custom-navigate

Create a browser history instance for legacy React Router integration. This history object will be used by Usertour.

```javascript
// history.js
import { createBrowserHistory } from 'history'

export default createBrowserHistory()
```

--------------------------------

### Deep Tour Button Actions

Source: https://docs.usertour.io/use-cases/choose-between-two-tours

Configure the 'Deep tour' button to dismiss the current chooser flow and start the 'Deep tour' flow.

```text
Dismiss flow
Start new flow/checklist: Deep tour
```

--------------------------------

### React Router v5 (Legacy) App Setup

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/set-custom-navigate

Wrap your React application with the Router component using the created history object. This sets up the context for React Router.

```javascript
// App.js
import { Router } from 'react-router-dom'
import history from './history'
import App from './App'

ReactDOM.render(
  <Router history={history}>
    <App />
  </Router>,
  document.body
)
```

--------------------------------

### SDK Auth Failed Error Message

Source: https://docs.usertour.io/api-reference-v2/mcp

Example of the error message triggered when there is a protocol mismatch between the instance URL and the client connection.

```text
SDK auth failed: Protected resource http://your-host/mcp does not match
expected https://your-host/mcp (or origin)
```

--------------------------------

### endAll()

Source: https://docs.usertour.io/developers/usertourjs-reference/content/end-all

Closes all active Usertour content displays for the current user. This includes flows, checklists, and other interactive guides. If no content is active, the method has no effect.

```APIDOC
## endAll()

### Description
Closes all active Usertour content displays for the current user. This includes flows, checklists, and other interactive guides. If no content is active, the method has no effect.

### Method
```javascript
usertour.endAll();
```

### Parameters
This method does not accept any parameters.

### Request Example
```javascript
usertour.endAll();
```

### Response
This method does not return a value. It operates by dismissing UI elements.
```

--------------------------------

### Track a User-Level Event with Company Context

Source: https://docs.usertour.io/developers/usertourjs-reference/events/track

This example demonstrates how to track an event specifically for the user, even when a company context is active via group(). Set `userOnly: true` within the options to ensure the event is not associated with the company. The user must be identified beforehand.

```javascript
usertour.track(
  'profile_email_updated',
  {
    source: 'settings'
  },
  {
    userOnly: true
  }
);
```

--------------------------------

### Integrate Custom Scroll Animation Library

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/set-custom-scroll-into-view

Integrate a third-party scroll animation library by providing its function to `setCustomScrollIntoView`. This example shows how to use a hypothetical `smoothScroll` library with custom duration, easing, and offset.

```javascript
usertour.setCustomScrollIntoView((element) => {
  // Using a hypothetical smooth-scroll library
  smoothScroll(element, {
    duration: 800,
    easing: "easeInOutCubic",
    offset: -100, // Add some top padding
  });
});
```

--------------------------------

### init()

Source: https://docs.usertour.io/developers/usertourjs-reference/setup/init

Initializes the Usertour SDK with your environment token. This method must be called once per page load before making any other Usertour.js calls.

```APIDOC
## init()

### Description
Initializes the Usertour SDK with your environment token. This method must be called once per page load before making any other Usertour.js calls.

### Parameters
#### Path Parameters
* **token** (string) - Required - Your Usertour environment token. You can find this token under [Settings → Environments](https://app.usertour.io/project/1/settings/environments). Each environment (e.g., Production, Staging) has its own unique token.

### Example
```javascript
// Initialize the Usertour SDK with your environment token
usertour.init('USERTOUR_TOKEN');
```

### Notes
* The `init()` method must be called before any other Usertour.js methods
* Each environment (Production, Staging, etc.) requires its own unique token
* The token is used to identify your environment and load the correct configuration
```

--------------------------------

### Continue Flow From Last Seen Step

Source: https://docs.usertour.io/use-cases/restart-onboarding-from-button

To allow users to resume an onboarding flow from where they left off, use `usertour.start()` with the `continue: true` option. This is useful for providing a seamless continuation experience.

```javascript
usertour.start("your_flow_id", {
  continue: true,
});
```

--------------------------------

### start_content

Source: https://docs.usertour.io/api-reference-v2/conditions-and-actions

Launches a specific flow or checklist content item.

```APIDOC
## start_content

### Description
Launches a flow or checklist by its contentId.

### Parameters
- **type** (string) - Required - Must be "start_content"
- **content** (string) - Required - The contentId of the flow or checklist to launch.
- **step** (string) - Optional - The cvid of a specific step within the launched flow to start at.
```

--------------------------------

### Configure .env file

Source: https://docs.usertour.io/open-source/env

Create a .env file in the project root directory with the required environment variables. Ensure all sensitive keys and passwords are replaced with secure values before deployment.

```env
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DATABASE_DIRECT_URL=postgresql://user:password@localhost:5432/dbname

# Server Configuration
NEST_SERVER_PORT=3000
NODE_ENV=production

# Email Service Configuration
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USER=your_email@example.com
EMAIL_PASS=your_email_password

# Redis Configuration
Redis_HOST=localhost
Redis_PORT=6379
Redis_PASS=

# Application Configuration
APP_HOMEPAGE_URL=http://localhost:8011
API_URL=
DOC_URL=https://docs.usertour.com
USERTOUR_TOKEN=your_token

# AWS S3 Configuration
AWS_S3_REGION=your_region
AWS_S3_ENDPOINT=your_endpoint
AWS_S3_ACCESS_KEY_ID=your_access_key
AWS_S3_SECRET_ACCESS_KEY=your_secret_key
AWS_S3_BUCKET=your_bucket
AWS_S3_DOMAIN=your_domain

# Analytics Configuration
POSTHOG_KEY=your_posthog_key
POSTHOG_HOST=your_posthog_host

# OpenTelemetry Configuration
OTLP_TRACES_ENDPOINT=
OTLP_METRICS_ENDPOINT=

# Encryption (run `openssl rand -hex 32` to generate)
ENCRYPTION_KEY=replace_with_64_hex_chars

# JWT Configuration
JWT_SECRET=your_jwt_secret
JWT_EXPIRATION_TIME=1h
JWT_REFRESH_EXPIRATION_TIME=7d

# Email Authentication
EMAIL_AUTH_ENABLED=true
EMAIL_SENDER=Your App <support@example.com>

# GitHub Authentication
GITHUB_AUTH_ENABLED=true
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
# Optional — defaults to <API_URL>/api/auth/github/callback when unset
GITHUB_CALLBACK_URL=http://localhost:8011/api/auth/github/callback

# Google Authentication
GOOGLE_AUTH_ENABLED=true
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Optional — defaults to <API_URL>/api/auth/google/callback when unset
GOOGLE_CALLBACK_URL=http://localhost:8011/api/auth/google/callback

# SSO (OIDC) — optional callback override; defaults to <API_URL>/api/auth/sso/callback
SSO_CALLBACK_URL=

# Outbound Security
# Set to true only if your SSO identity provider is reachable on an internal network
ALLOW_PRIVATE_NETWORK_EGRESS=false

# AI Provider (optional — enables machine translation)
# anthropic (default) | openai-compatible | bedrock
AI_PROVIDER=anthropic
AI_API_KEY=your_ai_api_key
AI_MODEL=claude-opus-4-8
# Required for openai-compatible, e.g. https://api.openai.com/v1
AI_BASE_URL=
# bedrock only — region falls back to AWS_REGION; credentials fall back to the AWS default chain
AI_AWS_REGION=
AI_AWS_ACCESS_KEY_ID=
AI_AWS_SECRET_ACCESS_KEY=
```

--------------------------------

### Initialize and Identify with npm

Source: https://docs.usertour.io/developers/usertourjs-installation

Import the module and initialize it with your token, then identify the current user with their details.

```javascript
import usertour from 'usertour.js';

usertour.init('USERTOUR_TOKEN');
usertour.identify('USER_ID', {
  name: 'USER_NAME',
  email: 'USER_EMAIL',
  signed_up_at: 'USER_SIGNED_UP_AT',
});
```

--------------------------------

### Define a columns block

Source: https://docs.usertour.io/api-reference-v2/blocks

Example of a columns block containing two side-by-side columns with different content types.

```json
{
  "type": "columns",
  "columns": [
    { "width": { "unit": "percent", "value": 50 }, "blocks": [{ "type": "text", "markdown": "Left" }] },
    { "blocks": [{ "type": "image", "url": "https://example.com/x.png" }] }
  ]
}
```

--------------------------------

### Initialize and Identify User with Usertour.js

Source: https://docs.usertour.io/developers/usertourjs-reference/overview

Initialize the SDK with your Usertour.js token and identify the current user with their details. Replace placeholders with actual values.

```javascript
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',
});
```

--------------------------------

### Define a rating question block

Source: https://docs.usertour.io/api-reference-v2/blocks

Example of a basic question block using the rating kind with a star style.

```json
{
  "type": "question",
  "question": { "kind": "rating", "name": "Satisfaction", "style": "star", "range": { "low": 1, "high": 5 } }
}
```

--------------------------------

### Initialize Usertour SDK

Source: https://docs.usertour.io/developers/usertourjs-reference/setup/init

Call this method once per page load before any other Usertour.js calls. Ensure you use your specific environment token.

```javascript
usertour.init('USERTOUR_TOKEN');
```

--------------------------------

### Restart Onboarding Button Click Handler

Source: https://docs.usertour.io/use-cases/restart-onboarding-from-button

Add a click event listener to a button to call `usertour.start()` with the flow ID when clicked. Ensure Usertour is initialized and the user is identified before this function is called.

```javascript
document.querySelector("#restart-onboarding").addEventListener("click", () => {
  usertour.start("your_flow_id");
});
```

--------------------------------

### URL Fragment Example

Source: https://docs.usertour.io/how-to-guides/urls

Identifies the fragment component of a URL, which comes after the '#' symbol and is often used in SPAs for client-side routing.

```html
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                                                    \____/
                                                       |
                                                    fragment
```

--------------------------------

### Create a feature onboarding flow

Source: https://docs.usertour.io

Requirements for building a user onboarding flow for specific features, ensuring design consistency and genuine user value.

```text
Using Usertour, build a user onboarding flow for the Create Task feature.

Requirements:
- The visual theme must match the website's existing design.
- The flow must be production-ready and suitable for launch.
- Every step should provide genuine value to users. Avoid adding steps
  simply for the sake of having a flow — the experience should help users
  understand and successfully use the feature.
```

--------------------------------

### Configure self-hosted Usertour MCP URL

Source: https://docs.usertour.io/build-onboarding-with-ai

Environment variable setting to point the plugin to a self-hosted Usertour instance.

```bash
export USERTOUR_MCP_URL="https://<your-usertour-host>/mcp"
```

--------------------------------

### 405 Not Allowed Error Response

Source: https://docs.usertour.io/api-reference-v2/mcp

Example of the error output when the client attempts to POST to the web root instead of the specific MCP endpoint.

```text
Error POSTing to endpoint: <html>...<h1>405 Not Allowed</h1>...
```

--------------------------------

### Analyze onboarding checklist friction

Source: https://docs.usertour.io/use-cases/analyze-onboarding-with-ai

Use this prompt to evaluate user progress, completion rates, and friction points within onboarding checklists.

```text
Use the Usertour MCP to analyze the User List onboarding checklist from
the last 30 days.

For every checklist item, report:

* Number of users who started it
* Number and percentage who completed it
* Manual versus automatic completions, if available
* Median time to completion
* Related flow launch and completion rates
* The most common completion order

Identify the checklist items that contribute most to activation and the
items that create the most friction. Recommend whether any items should
be reordered, rewritten, merged, or removed. Do not make changes.
```

--------------------------------

### Standardized List Object Response

Source: https://docs.usertour.io/api-reference-v2/pagination

Example of the JSON structure returned by list endpoints, including the results array and pagination links.

```json
{
  "results": [
    { "id": "cm9f6vwed0002iejc4vg2zu3t", "object": "content", "type": "flow", "..." : "..." },
    { "id": "cm9jaftye007yrjlx3ghggigi", "object": "content", "type": "checklist", "..." : "..." }
  ],
  "next": "/v2/projects/{projectId}/content?limit=2&cursor=cm9jaftye007yrjlx3ghggigi",
  "previous": null
}
```

--------------------------------

### Create PostgreSQL Database Backup

Source: https://docs.usertour.io/open-source/backups

Use this command to create a full backup of your PostgreSQL database. Replace placeholders with your actual database connection details.

```bash
pg_dump -h <host> -p <port> -U <username> -W <database_name> > backup.sql
```

--------------------------------

### Configure Usertour.js for Self-Hosting

Source: https://docs.usertour.io/open-source/usertourjs

Add this script to the <head> section of your HTML document to define the environment variables required for self-hosted operation.

```html
<script>
  window.USERTOURJS_ENV_VARS = {
    // WebSocket connection URL
    WS_URI: "http://localhost:8011/",
    
    // Base URL for SDK assets
    ASSETS_URI: "http://localhost:8011/sdk/",
    
    // Modern JavaScript bundle (ES2020)
    USERTOURJS_ES2020_URL: 'http://localhost:8011/sdk/es2020/usertour.js',
    
    // Legacy JavaScript bundle (IIFE)
    USERTOURJS_LEGACY_URL: "http://localhost:8011/sdk/legacy/usertour.iife.js"
  };
</script>
```

--------------------------------

### Configure Usertour MCP Server

Source: https://docs.usertour.io/api-reference-v2/mcp

Add this configuration to your MCP settings to enable the Usertour server.

```json
{
  "mcpServers": {
    "Usertour": {
      "url": "https://mcp.usertour.io/mcp"
    }
  }
}
```

--------------------------------

### Find Content ID from URL

Source: https://docs.usertour.io/how-to-guides/starting-flows

Locate the unique identifier for a flow or checklist by examining the URL of its detail page. This ID is necessary for programmatic starts.

```text
https://app.usertour.io/env/1/flows/cmaw8v1ch013s147h0uw8aha5/detail
```

--------------------------------

### Create an adoption checklist

Source: https://docs.usertour.io

Requirements for creating a checklist for feature adoption, emphasizing integration with onboarding flows and visual consistency.

```text
Create a checklist for the features on the User List page.

Requirements:
- Combine the checklist with relevant onboarding flows to significantly
  improve product adoption.
- Ensure production-level quality.
- Match the checklist's visual theme to the website's existing style.
```

--------------------------------

### Close All Usertour Content

Source: https://docs.usertour.io/developers/usertourjs-reference/content/end-all

Call the endAll() method to dismiss all active Usertour flows, checklists, and guides. This is useful for resetting the user's interactive experience.

```javascript
usertour.endAll();
```

--------------------------------

### Get question analytics

Source: https://docs.usertour.io/llms.txt

Retrieves per-question aggregates for survey questions, including answer distribution, NPS scores, and rating averages with rolling-window daily series.

```APIDOC
## GET /analytics/questions

### Description
Retrieves per-question aggregates for survey questions in the content. Includes answer distribution, NPS score with promoter/passive/detractor shares, and rating averages, each with a rolling-window daily series.
```

--------------------------------

### Clone Usertour Repository

Source: https://docs.usertour.io/open-source/local-development

Clone the Usertour repository to your local machine after forking it. Navigate into the cloned directory.

```shell
git clone git@github.com:<your-github-username>/usertour.git
cd usertour
```

--------------------------------

### goto_step

Source: https://docs.usertour.io/api-reference-v2/conditions-and-actions

Transitions the user to a specific step within the current flow.

```APIDOC
## goto_step

### Description
Transitions the user to a specific step identified by a key or cvid.

### Parameters
- **type** (string) - Required - Must be "goto_step"
- **step** (string) - Required - Target step key or cvid.
```

--------------------------------

### usertour.group(groupId, attributes, options)

Source: https://docs.usertour.io/developers/usertourjs-reference/companies/company

Associates the current user with a company and updates company attributes. Call this method when a user starts working with a specific company or switches to a new one.

```APIDOC
## usertour.group(groupId, attributes, options)

### Description
Associates the current user with a company and optionally updates company attributes. This method should be called whenever a user is working with a specific company or switches to a different one.

### Parameters
- **groupId** (string) - Required - The unique identifier for the company in your system.
- **attributes** (object) - Optional - Company attributes to update. These are merged with existing attributes.
- **options.membership** (object) - Optional - Membership attributes to update for the user's relationship with the company (e.g., role, department).
- **options.token** (string) - Optional - An identity token (JWT) required when identity verification is enabled. The token must have a `sub` claim equal to the user ID and a `companyId` claim equal to the `groupId`.

### Returns
A `Promise` that resolves when the group association is complete.

### Example
```javascript
usertour.group('comp_123456', {
  name: 'Acme Corp',
  industry: 'Technology',
  employee_count: 500
}, {
  membership: {
    role: 'admin',
    department: 'engineering',
    join_date: '2023-01-01T00:00:00.000Z'
  }
});
```
```

--------------------------------

### Track a Simple Product Event

Source: https://docs.usertour.io/developers/usertourjs-reference/events/track

Use this snippet to record a basic product action without any additional data. Ensure the user has been identified prior to calling this method.

```javascript
usertour.track('workspace_created');
```

--------------------------------

### navigate

Source: https://docs.usertour.io/api-reference-v2/conditions-and-actions

Navigates the user to a specified URL.

```APIDOC
## navigate

### Description
Navigates the user to an absolute or relative URL.

### Parameters
- **type** (string) - Required - Must be "navigate"
- **url** (string) - Required - The destination URL.
- **newTab** (boolean) - Optional - If true, opens the URL in a new browser tab.
```

--------------------------------

### Register Custom Input Using Text Content

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/register-custom-input

Use this when the value of your custom input is directly displayed as text content within the matched element. No additional setup is required beyond the CSS selector.

```html
<label>Favorite Fruit</label>
<div class="combo-box">
  <div class="combo-box-value">Apple</div>
  <div class="combo-box-trigger">▼</div>
</div>
```

```javascript
usertour.registerCustomInput(".combo-box-value");
```

--------------------------------

### Recommended Flow Structure

Source: https://docs.usertour.io/use-cases/choose-between-two-tours

Maintain separate flows for the chooser, simple tour, and deep tour for better maintainability and analytics.

```text
One chooser flow
One simple tour
One deep tour
```

--------------------------------

### Configure Event Rule for Follow-Up Flow

Source: https://docs.usertour.io/use-cases/close-button-follow-up

Sets up an event rule to trigger a follow-up flow only after a specific original flow has been dismissed or ended by the user.

```text
Event
Flow Dismissed/Ended
at least 1 time
at any point in time
by current user in any company

Where
Flow ID is your original flow ID
```

--------------------------------

### Register Custom Input with Custom getValue Function

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/register-custom-input

Use this for complex custom inputs where the desired value is not the element's text content. Provide a function to extract the value, for example, from a nested input or a data attribute.

```html
<label>Select City</label>
<div class="location-picker" data-city-id="123">
  <input type="text" value="San Francisco" readonly />
  <div class="location-picker-icon">📍</div>
</div>
```

```javascript
usertour.registerCustomInput(".location-picker", (element) => {
  // Grab the nested input's value
  const input = element.querySelector("input");
  return (input && input.value) || "";
});
```

--------------------------------

### Wildcard Path Matching

Source: https://docs.usertour.io/how-to-guides/urls

Demonstrates wildcard matching for paths. Use '*' to match any path segment or sequence of segments according to specific rules.

```js
// 1. /app/*
//    * ✅ Matches /app/one, /app/one/two
//    * ❌ Does not match /app
//    * Note: Requires at least one segment after /app/

// 2. /app*
//    * ✅ Matches /app, /applications
//    * Note: Matches anything that starts with app

// 3. /*/projects
//    * ✅ Matches /app/projects, /app/one/two/three/projects
//    * Note: Matches projects at any depth

```

--------------------------------

### Next.js Integration

Source: https://docs.usertour.io/developers/usertourjs-reference/advanced/set-custom-navigate

Configure Usertour to use Next.js router's push method. Import and use the useRouter hook.

```javascript
// For Next.js
import { useRouter } from 'next/router'

const router = useRouter()
usertour.setCustomNavigate(url => router.push(url))
```

--------------------------------

### Fragment Patterns

Source: https://docs.usertour.io/how-to-guides/urls

Demonstrates defining patterns for URL fragments, similar to path matching, using dynamic segments and wildcards.

```js
#/projects/:project/dashboard
```

```js
#/projects/:project/dashboard/*
```

--------------------------------

### showResourceCenterLauncher()

Source: https://docs.usertour.io/developers/usertourjs-reference/resource-center/show-resource-center-launcher

Makes the resource center launcher button visible. This method requires `usertour.js` version 0.0.20 or later. The launcher visibility is a global setting and is applied as soon as a resource center activates.

```APIDOC
## showResourceCenterLauncher()

### Description
Shows the resource center launcher button. This is the inverse of `hideResourceCenterLauncher()`.

### Method
`usertour.showResourceCenterLauncher()`

### Parameters
None.

### Returns
`void`

### Example
```javascript
// Re-show the launcher when the user leaves a distraction-free view
exitFocusMode(() => {
  usertour.showResourceCenterLauncher();
});
```
```

--------------------------------

### Follow-Up Tooltip Message

Source: https://docs.usertour.io/use-cases/close-button-follow-up

Provides a concise message for a follow-up tooltip, informing the user how to restart onboarding.

```text
You can restart onboarding from here anytime.
```

--------------------------------

### Restore PostgreSQL Database from Backup

Source: https://docs.usertour.io/open-source/backups

Use this command to restore your PostgreSQL database from a previously created backup file. Ensure you replace placeholders with your actual database connection details.

```bash
psql -h <host> -p <port> -U <username> -W <database_name> < backup.sql
```

--------------------------------

### Identify with Recommended Attributes

Source: https://docs.usertour.io/developers/usertourjs-reference/users/identify

Registers a user while providing additional profile information for personalization.

```javascript
// Identify a user with recommended attributes
usertour.identify('123456', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  signed_up_at: '2021-06-14T16:25:49Z'
});
```
Tokens:
Raw