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

# Amplitude — How to setup

> Learn how to stream live user activity from Amplitude into Autoplay to give your support AI agent real-time context on what every user is doing.

## ⚡ Add this skill

<CardGroup cols={2}>
  <Card title="One command" icon="terminal">
    Add the Autoplay Amplitude session replay provider skill for an existing Amplitude setup.

    <CodeGroup>
      ```bash CLI theme={null}
      uvx --from autoplay-sdk autoplay-install-skills --user-activity amplitude
      ```
    </CodeGroup>

    <a className="skill-card-link" href="/recipes/amplitude/how-to-setup">View the docs →</a>
  </Card>

  <Card title="Agent onboarding" icon="robot">
    Fetch this skill when a customer already uses Amplitude as a session replay provider and wants Autoplay live user activity.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -s https://developers.autoplay.ai/activity-amplitude/SKILL.md
      ```
    </CodeGroup>

    <a className="skill-card-link" href="https://developers.autoplay.ai/activity-amplitude/SKILL.md" target="_blank">View the skill →</a>
  </Card>
</CardGroup>

**Prerequisite:** install the SDK first — see [Quickstart](/quickstart).

<Tip>
  This guide assumes you **already have Amplitude set up** and capturing events in your app. If you don't yet, sign up and create a project at [amplitude.com](https://amplitude.com) — see [Amplitude's getting-started docs](https://amplitude.com/docs/get-started/amplitude-quickstart) for account/project setup — then come back here.
</Tip>

**What Autoplay needs from your Amplitude project:**

* **API Key** — already in your `amplitude.initAll()` call (Step 2 below). Find it under **Settings → Projects → \[Your Project] → General** if you need to re-verify it.
* **Project ID** — links your Amplitude project to your Autoplay `product_id` (**Settings → Projects → select your project → Project ID**; used in Step 4).

<Warning>
  If you're setting up a **brand-new** Amplitude project, note that Amplitude shows a **"Let's get set up!"** screen with **"Waiting for your events..."** at the bottom, and blocks **Data → Destinations** until it's dismissed. Complete Steps 1–3 below to send first events, then click **"Finish Setup"** — or **"Skip for now"** to go straight to the dashboard. This doesn't apply if Amplitude is already live in your app.
</Warning>

***

### 🎯 Step 1 — Verify the existing Amplitude SDK

Confirm your app already has `@amplitude/unified` installed with Analytics and Session Replay enabled — this is the one that bundles both in one package, which Autoplay needs (Session Replay lets Autoplay correlate what users actually did on screen with your support AI agent conversations). If you're on the older `@amplitude/analytics-browser` package instead, that's a migration decision — see [Amplitude's browser SDK docs](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2).

Don't have it installed yet? Run this in your frontend app's directory:

```bash theme={null}
npm install @amplitude/unified
```

**📺 Full setup walkthrough**

<iframe src="https://app.arcade.software/share/wRkSFI6KddHoaT8SBCbd" title="Set up Amplitude in your app" width="100%" height="500" allow="fullscreen" style={{ borderRadius: "8px", border: "none" }} />

***

### 💻 Step 2 — Verify initialization and autocapture

<Warning>
  **This step is required before you can create a destination in Step 5.** Amplitude only shows the **Data → Destinations** section and the destination catalog after it has received at least one live event from your app.
</Warning>

Your app should already call `amplitude.initAll()` once at startup (`main.ts`, `_app.tsx`, or root layout) — see [Amplitude's browser SDK docs](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) for the general init pattern and where to find your API key if you need to check it.

**📺 Copy your Amplitude API key**

<iframe src="https://app.arcade.software/share/ycesTzu0o9kI2N56wytr" title="Copy your Amplitude API key" width="100%" height="500" allow="fullscreen" style={{ borderRadius: "8px", border: "none" }} />

Confirm your existing `initAll()` call has `autocapture: true` set — this is the one setting Autoplay actually requires:

```typescript theme={null}

 amplitude.initAll('YOUR_AMPLITUDE_API_KEY', {
  analytics: { autocapture: true },   // required — without this, no click/pageview events reach Autoplay
  sessionReplay: { sampleRate: 1 },
});
```

If Amplitude isn't already showing events for your app, send it some first: open your app, click around a few pages, and confirm under **Activity → Live Events**. (On a brand-new project, this also unlocks **Data → Destinations** — click **"Finish Setup"** once events appear.)

***

### 👤 Step 3 — Identify on login (required for session scoping)

Add this to your auth/login handler — wherever your app handles a successful login. `setUserId` is the key step: it stamps every event with a stable `user_id`, and the connector keys a user's activity under exactly that id — the same one your agent will look them up by.

```typescript theme={null}
import * as amplitude from '@amplitude/unified';

amplitude.setUserId(user.id);   // the stable id your agent reads activity by

const identifyObj = new amplitude.Identify();
identifyObj.set('email', user.email);
identifyObj.set('name', user.name);
amplitude.identify(identifyObj);
```

<Warning>
  Without `setUserId`, events carry only a `device_id` — the connector still records activity, but keyed by `device_id`, so your agent won't find the user by their real id. Always call `setUserId` on login.
</Warning>

On logout — reset so the next user starts clean:

```typescript theme={null}
amplitude.reset()
```

<Note>
  **About session IDs:** Amplitude assigns each session a numeric Unix-millisecond timestamp as its ID. The connector converts it to a string automatically. If `session_id` is `-1` in very early events, the connector falls back to `device_id` until the session resolves (a few seconds).
</Note>

***

### 📝 Step 4 — Register your product with Autoplay

Now that your app is capturing events, we need to create a secure "ingest\_url" and a shared secret (`ingest_secret`) so that data can be safely sent to Autoplay.

<Tip>
  **Where to find your Amplitude Project ID:** In Amplitude, go to **Settings → Projects → select your project → Project ID**. Copy the numeric ID shown there — you'll use it as `YOUR_AMPLITUDE_PROJECT_ID` below.
</Tip>

**📺 How to find your Amplitude Project ID**

<iframe src="https://app.arcade.software/share/gbMSMIenMpBYhCWbLFrh" title="Find your Amplitude Project ID" width="100%" height="500" allow="fullscreen" style={{ borderRadius: "8px", border: "none" }} />

The `autoplay-sdk` was installed on the [Quickstart](/quickstart) page. Create a Python file with the script below, replace the placeholders with your values, and run it once:

```python theme={null}
import asyncio
from autoplay_sdk.admin import onboard_product
from autoplay_sdk.providers import AmplitudeProvider

async def main() -> None:
    result = await onboard_product(
        "YOUR_AMPLITUDE_PROJECT_ID",    # your Amplitude project ID from above
        contact_email="you@yourcompany.com",  # replace with your actual email
        user_activity_provider=AmplitudeProvider(),
        print_operator_summary=True,
    )

asyncio.run(main())
```

This will print the following fields:

* **product\_id:** `YOUR_AMPLITUDE_PROJECT_ID`
* **provider:** `amplitude`
* **ingest\_url:** `https://connector.autoplay.ai/ingest/YOUR_AMPLITUDE_PROJECT_ID`
* **ingest\_secret:** `{secret}` — Amplitude sends this as `Authorization: Bearer <ingest_secret>`
* **mcp\_url:** `https://mcp.autoplay.ai/mcp`
* **mcp\_key:** `{secret}` — your agent's Bearer token

**Save what prints in the terminal** — you will need `ingest_url` and `ingest_secret` in Step 5 below, and `mcp_key` when you connect your AI support agent.

<Note>
  **Re-registering your product**

  A second `onboard_product` with the same `product_id` returns **409** until overwrite is allowed. Pass **`force=True`** to overwrite. You must still pass **`contact_email`** on every registration, including overwrites.
</Note>

***

### ⚙️ Step 5 — Create the event streaming destination in Amplitude

You'll need two values printed by Step 4:

* **URL:** `ingest_url` (e.g. `https://connector.autoplay.ai/ingest/YOUR_AMPLITUDE_PROJECT_ID`)
* **Bearer token:** `ingest_secret`

**📺 How to create the Amplitude event streaming destination**

<iframe src="https://app.arcade.software/share/NeCcl6dtC7DQdjOjue28" title="Create Amplitude Event Streaming Destination" width="100%" height="500" allow="fullscreen" style={{ borderRadius: "8px", border: "none" }} />

Amplitude uses a **developer portal** to create custom event streaming destinations. Opening the destination builder (**Data → Destinations → + Add Destination → search "HTTP" → Event Streaming**) is standard Amplitude navigation — see [Amplitude's HTTP destination docs](https://amplitude.com/docs/data/destination-catalog/http) if you need the general walkthrough. The Autoplay-specific part is what you configure once you're there:

**Fill in the Configuration tab**

**Integration Name** — give the destination a name, e.g. `autoplay-connector`.

**URL Endpoint**

| Field  | Value                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------- |
| Method | `POST`                                                                                                |
| URL    | Your `ingest_url` from Step 4 (e.g. `https://connector.autoplay.ai/ingest/YOUR_AMPLITUDE_PROJECT_ID`) |

**Create Parameters** — click **"Add New Parameter"** and add:

| Parameter name | Value                                                                        |
| -------------- | ---------------------------------------------------------------------------- |
| `apiKey`       | `Bearer ` + your `ingest_secret` from Step 4 (e.g. `Bearer <ingest_secret>`) |

**REST API Headers** — click **"Add New REST API Header"** and set:

| Header Key      | Header Value           |
| --------------- | ---------------------- |
| `Authorization` | `${parameters.apiKey}` |

**Event Body Editor** — replace the default Freemarker template with:

<AccordionGroup>
  <Accordion title="Amplitude destination — Freemarker event body template (expand to copy)">
    ```
    <#setting number_format="0.####">
    <#assign et = input.event_type!''>
    <#assign ep = input.event_properties!{}>
    <#assign up = input.user_properties!{}>

    {
      "events": [
        {
          "event_type": "<#if et?starts_with('Viewed') || et == '[Amplitude] Page Viewed' || et == 'Page Viewed'>$pageview<#elseif et == '[Amplitude] Element Clicked' || et == '[Amplitude] Element Changed' || et?starts_with('Form')>$autocapture<#else>${et}</#if>",
          "user_id": "${input.user_id!''}",
          "device_id": "${input.device_id!''}",
          "session_id": ${input.session_id!0},
          "time": ${input.time!0},
          "user_properties": {
            <#list up?keys as k>"${k}": "${up[k]}"<#sep>, </#sep></#list>
          },
          "event_properties": {
            "[Amplitude] Page URL": "${ep['Page URL']!ep['Page Location']!ep['[Amplitude] Page URL']!ep['[Amplitude] Page Location']!''}",
            "[Amplitude] Page Title": "${ep['Page Title']!ep['[Amplitude] Page Title']!''}",
            "$event_type": "<#if et == '[Amplitude] Element Changed'>change<#elseif et?starts_with('Form Submitted')>submit<#elseif et?starts_with('Form Started')>focus<#else>click</#if>",
            "$current_url": "${ep['Page URL']!ep['Page Location']!ep['[Amplitude] Page URL']!ep['[Amplitude] Page Location']!''}",
            "$button_text": "${ep['[Amplitude] Element Text']!ep['Element Text']!ep['Page Title']!''}",
            "$elements_chain": "${ep['[Amplitude] Element Path']!ep['[Amplitude] Element Hierarchy']!ep['Element Path']!''}",
            "$element_id": "${ep['[Amplitude] Element ID']!ep['Element ID']!''}",
            "$element_tag": "${ep['[Amplitude] Element Tag']!ep['Element Tag']!''}"
          }
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  This template does two things the default Amplitude template does not:

  **1. Event type normalisation** — Amplitude's autocapture sends events with names like `[Amplitude] Page Viewed` and `[Amplitude] Element Clicked`. The Autoplay connector needs these mapped to standard names it recognises. The template does that automatically:

  | Amplitude event                                                        | Normalised to            |
  | ---------------------------------------------------------------------- | ------------------------ |
  | `[Amplitude] Page Viewed`, `Page Viewed`, `Viewed *`                   | `$pageview`              |
  | `[Amplitude] Element Clicked`, `[Amplitude] Element Changed`, `Form *` | `$autocapture`           |
  | Everything else                                                        | passed through unchanged |

  **2. Field mapping** — Amplitude stores click details (element text, URL, element path) under its own field names. The template copies them into the fields Autoplay expects so it can generate human-readable descriptions like "User clicked Sign Up button on the dashboard page".

  Without this template, only page views appear in the Autoplay stream — clicks and form events are silently ignored.
</Note>

On the Testing tab: enable **Send Events** (keep **All Events**), click **Test Connection** to confirm a `200 OK`, then **Release** to publish the destination. Finally, back in **Data → Destinations**, open your published destination and **Add New Sync** to activate it — standard Amplitude steps, not Autoplay-specific.

The sync is now active. Amplitude will stream all events to your connector endpoint in real time.

> **👋 Quick Tip:** Once you add this code to your site, jump into our [Discord](https://discord.gg/jCbR2tQA5) and say hi — we will check your data is flowing and help you get fully set up!

### 🔌 Next: connect your AI support agent

Your activity is now flowing into the connector. Head back to Quickstart to choose your existing AI support agent and connect it via MCP — it then pulls a user's live activity on demand, the moment it needs context to answer.

<Card title="Choose your AI support agent" icon="comments" href="/quickstart#-step-2-—-connect-your-ai-support-agent">
  Fin (Intercom), Maven, Ada, Botpress, and more — pick yours and connect via MCP.
</Card>