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

> Connects Appcues as the visual-tour delivery layer for Autoplay's proactive nudge stream. Covers installing and identifying the Appcues SDK, building a flow in Appcues Studio, and setting tour_provider to "appcues" in the onboarding config so Autoplay.js's dispatchNudge launches the flow automatically. Also covers the manual EventSource fallback for teams not using Autoplay.js. Use when the customer already uses Appcues, or asks how to make a proactive Autoplay nudge open a guided product tour.

# Visual User Tour — Appcues

> Read `autoplay-core` first for install and credentials (`product_id`, `mcp_url`,
> `mcp_key`). This skill assumes the customer already has, or will build, an
> Appcues account; it does not replace the AI support agent — pair it with a
> `chatbot-*` skill (e.g. `chatbot-maven`) for the proactive prompt that offers
> the tour in the first place. Appcues only renders the tour once something
> else (the chatbot's proactive layer, or Autoplay's own nudge card) has
> already offered it and the user said yes.
>
> **Who does this: Mixed.** Installing the Appcues snippet and building the
> Flow in Appcues Studio (**Flows → Build a Flow**) are human-only, dashboard
> steps — there's no API for either. The `Appcues.identify` / `Appcues.page()`
> calls, wiring `tour_provider` into the onboarding config, the optional
> manual `EventSource` trigger path, and reporting `flow_completed` back are
> all code you write yourself.
>
> **Stay inside this project's directory tree.** Every file this skill
> touches lives inside the current project root. Never search, list, or read
> outside it.
>
> **Onboarding config isn't self-serve yet.** Draft the `tour_provider` /
> `tours` JSON below, but the change only takes effect once the customer
> shares it with the Autoplay team in Discord — don't tell the customer the
> tour is wired up until that round-trip happens.

## How Appcues fits into the proactive layer

Appcues is a delivery channel, not the thing that decides *when* to show a
tour. If [Autoplay.js](https://developers.autoplay.ai/quickstart#-step-3-—-add-the-proactive-layer)
is already connected (recommended), the whole path is:

```
Autoplay detects a milestone from live activity
        ↓
Autoplay.js receives a "tour" nudge over the nudge stream
        ↓
Autoplay.dispatchNudge(nudge) calls Appcues.show(flow_id) for you
        ↓
Appcues renders the guided flow in the browser
```

No customer-hosted stream-proxy or manual trigger code is needed in this
path — only the Appcues-specific setup below (install, identify, build the
flow, set `tour_provider`). If Autoplay.js isn't connected yet, do that
first — it's what actually fires the tour and also unlocks Autoplay's
provider-agnostic nudge card. Only use the manual path (Step 4 below) when
Autoplay.js is deliberately not in use.

## Step 1 — Install and identify Appcues

Add the loader snippet, using the account ID from the customer's **Settings →
Installation** page in Appcues (human-only — there's no API to fetch it):

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

If loading it dynamically instead of a static tag, append 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);
```

Once loaded and the user is known, identify them with the **same stable id**
used for the activity source (`posthog.identify(user.id)` /
`amplitude.setUserId(user.id)`) — never email or a session id:

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

Call `Appcues.page()` again on every client-side route change so Appcues can
re-evaluate page-targeted flows. Do this before calling `Autoplay.connectNudges(...)`
so Appcues is ready the moment a tour nudge arrives.

## Step 2 — Build the flow in Appcues Studio (human-only)

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

There is no API shortcut for this — it's a dashboard step the customer does
themselves.

## Step 3 — Wire `tour_provider` into the onboarding config

Autoplay's onboarding config maps each milestone workflow to a flow in the
configured provider:

```json theme={null}
{
  "product_id": "your-product-id",
  "tours": [
    {
      "workflow_key": "connect_account",
      "name": "Connect your account",
      "flow_id": "your-appcues-flow-id"
    }
  ],
  "tour_provider": "appcues"
}
```

* `tour_provider` must be the literal string `"appcues"` — a typo here is
  the most common reason a nudge never opens a tour.
* Each `tours[].flow_id` must be the exact Flow ID from Step 2, in the same
  Appcues workspace the loader snippet points at.
* Draft this against the customer's existing config (see `autoplay-core` /
  the Quickstart onboarding JSON) rather than replacing it wholesale — only
  add or update the `tours` entries and `tour_provider` key.

Once this config change has been applied by the Autoplay team, no extra
frontend trigger code is needed: `Autoplay.dispatchNudge(nudge)` already
calls `Appcues.show(flow_id)` for `"tour"`-type nudges.

## Step 4 — Manual path (only if not using Autoplay.js)

Skip this step if Autoplay.js is connected — Step 3 already covers it. Use
this only when the customer deliberately wires the nudge stream themselves.

Proxy the stream server-side (never expose the stream key to the browser),
connect with `EventSource`, and check both the event type and the session
before triggering:

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

`payload.flow_id` maps to the Flow ID from Step 2.

## Step 5 — Report completion back (optional)

Appcues emits `flow_completed`; feed it 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 also using Autoplay.js
});
```

## Failure modes

* **Tour never opens:** `tour_provider` isn't exactly `"appcues"`, or the
  config change was drafted but never actually sent to/applied by the
  Autoplay team.
* **`Appcues is not defined`:** a method was called before the loader
  script's `onload` fired.
* **Flow ID not found / wrong flow:** `flow_id` belongs to a different
  Appcues workspace than the one the loader snippet points at.
* **Wrong user targeted, or flow doesn't personalize:** the id passed to
  `Appcues.identify()` doesn't match the id the activity source (PostHog,
  Amplitude, …) uses.
* **Manual path only — tour fires for the wrong browser tab:** `session_id`
  check was skipped or compared against the wrong session source.

## Reference

* Appcues setup doc: [https://developers.autoplay.ai/recipes/appcues/how-to-setup](https://developers.autoplay.ai/recipes/appcues/how-to-setup)
* Base tour guide (payload structure, manual EventSource path): [https://developers.autoplay.ai/recipes/user-tour/overview](https://developers.autoplay.ai/recipes/user-tour/overview)
* Quickstart Step 3 (Autoplay.js, nudge dispatch) and Step 4 (visual guidance): [https://developers.autoplay.ai/quickstart](https://developers.autoplay.ai/quickstart)
* Autoplay core skill: `autoplay-core`
* Pair with a chatbot skill (e.g. `chatbot-maven`) for the proactive prompt that offers the tour