Userpilot — How to setup

Autoplay streams structured UI actions from your users’ browser sessions in real time. This tutorial wires that stream to Userpilot so that when the right moment arrives — a user stuck on a page, a first-time feature visit, a repeated error — your backend detects it and fires the correct Userpilot tour immediately. This tutorial builds on How to trigger a User Tour. Complete that guide first — it covers the proxy route, EventSource connection, and payload structure. This page covers only what is specific to Userpilot.

1. Install Userpilot

Add the snippet to your app and initialize it with your token from Settings → Environments.

<script>
  (function(w,u,p){var s=w.userpilot=w.userpilot||[];if(!s.initialized){
  s.initialized=!0;var t=u.createElement("script");t.type="text/javascript";
  t.async=!0;t.src="https://js.userpilot.io/sdk/latest.js";
  var f=u.getElementsByTagName("script")[0];f.parentNode.insertBefore(t,f);
  s.identify=s.identify||function(){s.push(["identify",arguments])};
  s.initialize=s.initialize||function(){s.push(["initialize",arguments])};
  s.trigger=s.trigger||function(){s.push(["trigger",arguments])};
  }})(window,document);
  userpilot.initialize("YOUR_APP_TOKEN");
</script>

import Userpilot from 'userpilot';
Userpilot.initialize('YOUR_APP_TOKEN');

2. Identify the user

Call this once the user is authenticated. Use the same userId you send to PostHog so Autoplay can match sessions correctly.

userpilot.identify(userId, {
  name: user.displayName,
  email: user.email,
  created_at: user.createdAt, // ISO 8601
});

3. Create a tour in Userpilot

In the Userpilot dashboard go to Flows → Create flow and build your tour.
Set any targeting rules you need (page URL, user segment, etc.).
Publish the tour.
Note the Flow ID shown in the URL bar (/flows/<flow_id>/edit).

4. Trigger the tour

In your onmessage handler from step 3 of the manual path, add the Userpilot trigger call:

events.onmessage = (event) => {
  const payload = JSON.parse(event.data);

  if (payload.type !== "usertour_trigger") return;

  const mySessionId = posthog?.get_session_id?.() ?? null;
  if (!mySessionId || payload.session_id !== mySessionId) return;

  userpilot.trigger(payload.flow_id);
};

The flow_id in the payload maps to the Flow ID of your Userpilot tour, visible in the URL when editing the tour in the Userpilot dashboard.

Who We Are

Get Started

Live User Activity

AI Support Agents

Visual User Tours

Receive events

🔌 Live activity via MCP

Build with events

Integration helpers

Context sources

Reference

Userpilot — How to setup

1. Install Userpilot

2. Identify the user

3. Create a tour in Userpilot

4. Trigger the tour

​1. Install Userpilot

​2. Identify the user

​3. Create a tour in Userpilot

​4. Trigger the tour

1. Install Userpilot

2. Identify the user

3. Create a tour in Userpilot

4. Trigger the tour