> ## Documentation Index
> Fetch the complete documentation index at: https://developers.autoplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Appcues — How to setup

> Trigger an Appcues tour from the Autoplay event stream.

<Note>
  Autoplay streams structured UI actions from your users' browser sessions in real time. This tutorial wires that stream to Appcues 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 Appcues flow immediately.
  This tutorial builds on [How to trigger a User Tour](/recipes/user-tour/overview). Complete that guide first — it covers the proxy route, EventSource connection, and payload structure. This page covers only what is specific to Appcues.
</Note>

## 1. Install Appcues

Add the snippet to your app using your account ID from **Settings → Installation**.

```html theme={null}
<script src="https://fast.appcues.com/YOUR_ACCOUNT_ID.js"></script>
```

If you're loading it yourself (e.g. in a Next.js effect) instead of a static `<script>` tag, append it to `document.body` and wait for `onload` before calling any `Appcues.*` method:

```javascript theme={null}
const script = document.createElement("script");
script.src = `https://fast.appcues.com/${accountId}.js`;
script.onload = () => {
  // window.Appcues is now available
};
document.body.appendChild(script);
```

## 2. Identify the user

Call this once the script has loaded and the user is known. Use the same `userId` you send to PostHog so Autoplay can match sessions correctly.

```javascript theme={null}
window.Appcues.identify(userId, {
  name: user.displayName,
  email: user.email,
  signed_up_at: user.createdAt, // ISO 8601
});
window.Appcues.page();
```

`Appcues.page()` tells Appcues the current URL has changed and lets it re-evaluate any flows targeted at that page — call it again on every client-side route change.

## 3. Create a flow in Appcues

1. In Appcues Studio go to **Flows → Build a Flow** and build your tour.
2. Use the builder to add steps — tooltips, modals, hotspots, or checklists — and attach each step to an element on your page.
3. Set any targeting rules you need (page URL, user segment, etc.), then publish the flow.
4. Note the **Flow ID** shown in the URL bar when editing the flow (`studio.appcues.com/.../flows/<flow_id>`).

## 4. Trigger the tour

<Note>
  If you're using [Autoplay.js](/quickstart#-step-3-—-connect-autoplay-js) (recommended), skip this step — once you've set `tour_provider` to `"appcues"`, `AP.dispatchNudge(nudge)` already calls `Appcues.show(flow_id)` for you when a `"tour"` nudge arrives. This step is only needed if you're wiring the manual `EventSource` path from the [base guide](/recipes/user-tour/overview) yourself.
</Note>

In your `onmessage` handler from [step 3 of the manual path](/recipes/user-tour/overview#3-understanding-the-payload), add the Appcues trigger call:

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

  window.Appcues.show(payload.flow_id);
};
```

The `flow_id` in the payload maps to the **Flow ID** of your Appcues flow, visible in the URL when editing the flow in Appcues Studio.

## 5. Report completion back (optional)

Appcues emits a `flow_completed` event you can listen for and feed back into Autoplay so adoption tracking knows the tour actually finished, not just that it was shown:

```javascript theme={null}
window.Appcues.on("flow_completed", () => {
  // e.g. nudgeHandle.report("tour_completed") if you're also using
  // Autoplay.js — see /quickstart#-step-3-—-connect-autoplay-js.
});
```