Amplitude — How to setup

⚡ Add this skill

One command

Add the Autoplay Amplitude session replay provider skill for an existing Amplitude setup.

uvx --from autoplay-sdk autoplay-install-skills --user-activity amplitude

View the docs →

Agent onboarding

Fetch this skill when a customer already uses Amplitude as a session replay provider and wants Autoplay live user activity.

curl -s https://developers.autoplay.ai/activity-amplitude/SKILL.md

View the skill →

Prerequisite: install the SDK first — see Quickstart.

Let an AI agent do this for you

Use the Amplitude agent skill to wire up the full integration autonomously — SDK install, identify wiring, server-side proxy, and CSP headers.

If you already use Amplitude to capture events, skip to Step 3 to register your product with Autoplay, then Step 4 to identify on login, and Step 5 to create the event streaming destination.

🏁 Before you begin, Create your Amplitude account and project

If you don’t have an Amplitude account yet:

Go to amplitude.com and sign up for a free account
After signing in, click Create new project and give it your app’s name
Amplitude shows your API Key on the welcome screen, keep this tab open, you’ll need it in Step 1
Your Project ID is at Settings → Projects → select your project → Project ID — you’ll need it in Step 3

When you first log in, Amplitude shows a “Let’s get set up!” screen with “Waiting for your events…” at the bottom. You cannot access Data → Destinations until this screen is dismissed. To dismiss it: complete Steps 1–3 below to send your first events, then click “Finish Setup” — or click “Skip for now” in the bottom-right to go straight to the dashboard.

🎯 Step 1 — Install the Amplitude SDK in your app

Open a terminal in your frontend app’s directory (the folder that contains your package.json) and run:

npm install @amplitude/unified

The Unified SDK (@amplitude/unified) bundles Analytics and Session Replay in one package. Session Replay lets Autoplay correlate what users actually did on screen with your support AI agent conversations. 📺 Full setup walkthrough

💻 Step 2 — Initialize on app load

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. If you skip or fail to complete this step, the catalog will be empty and you will not be able to add a destination.

Call amplitude.initAll() once at app startup — in main.ts, _app.tsx, or your root layout. Replace YOUR_AMPLITUDE_API_KEY with your project’s API key (see the Tip below for where to find it):

Where to find your Amplitude API key: In Amplitude, go to Settings → Projects → [Your Project] → General. Copy the API Key shown there. It’s also displayed on the onboarding wizard screen under “Your API Key”.

📺 Copy your Amplitude API key

import * as amplitude from '@amplitude/unified';

amplitude.initAll('YOUR_AMPLITUDE_API_KEY', {
  analytics: {
    autocapture: true, // auto-captures clicks, page views, form interactions
  },
  sessionReplay: {
    sampleRate: 1, // 1 = record 100% of sessions; lower in production if needed
  },
});

autocapture: true ensures that page views, clicks, and session lifecycle events flow to Autoplay automatically. Session Replay records what users actually do — Autoplay correlates those sessions to give your support AI agent real-time context. After adding the code above, interact with your app to send Amplitude its first events:

Open your app in a browser
Navigate to a few pages, click some buttons, and perform a typical user action
In Amplitude, go to Activity → Live Events and confirm events are arriving

Once Amplitude shows your events, the “Finish Setup” button at the bottom of the onboarding screen activates, click it to reach the main dashboard. You can then proceed to Step 3.

📝 Step 3 — Register your product with Autoplay

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.

📺 How to find your Amplitude Project ID

This script registers your product and prints the credentials you’ll need in Steps 4 and 6. Create the registration script — in your project root, create a file called register.py:

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",
        contact_email="you@yourcompany.com",
        user_activity_provider=AmplitudeProvider(),
        print_operator_summary=True,
    )

asyncio.run(main())

Run it once (make sure your venv is active):

Mac / Linux
Windows (PowerShell)

python3 register.py

python register.py

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, and mcp_key in Step 6.

Re-registering your productA 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.

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.

YOUR_AMPLITUDE_PROJECT_ID — your Amplitude project ID from Step 3 (e.g. 828048)

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

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.

On logout — reset so the next user starts clean:

amplitude.reset()

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

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

You’ll need two values printed by Step 3:

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

Amplitude uses a developer portal to create custom event streaming destinations. 5a — Open the destination builder

In Amplitude, click Data in the left sidebar
In the left sub-navigation, click Destinations
Click + Add Destination (top right)
In the catalog that opens, search for “HTTP” or scroll to find it, then select it
Choose “Event Streaming” as the type

5b — 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 3 (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 3 (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:

<#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']!''}"
      }
    }
  ]
}

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.

Click “Next” to proceed to the Testing tab. 5c — Configure and release on the Testing tab

Enable the “Send Events” toggle
Under “Select & filter events”, keep it set to “All Events”
Click “Test Connection” to send a test event and confirm you get a 200 OK
Click “Release” (top right) — this publishes the destination to the catalog

5d — Create a sync from the published destination

Go back to Data → Destinations
Under “New Destinations”, find your destination
Click it → “Add New Sync” page opens
Enter a Sync Name (e.g., production-stream) and click “Create Sync”

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

📡 Step 6 — See your activity land

Everything is wired up! The connector is pull-based — you (or your agent) fetch a user’s recent activity the moment you need it. Click around your app while logged in as an identified user, then pull that user’s activity with the mcp_key from Step 3:

curl "https://mcp.autoplay.ai/users/YOUR_AMPLITUDE_PROJECT_ID/YOUR_USER_ID/live-activity?limit=10" \
  -H "Authorization: Bearer YOUR_MCP_KEY"

YOUR_USER_ID — the stable id you pass to amplitude.setUserId(...).
YOUR_MCP_KEY — the mcp_key printed by Step 3.

A 200 with a populated actions array means your events are flowing. An empty array means events haven’t landed yet — click around and give it a few seconds.

This REST call returns the exact same data your agent reads over MCP (the get_live_user_activity tool). See the MCP server page to connect your agent.

Common issues:

401: Confirm Amplitude’s destination Authorization header is Bearer <ingest_secret> (from Step 3) and the destination URL is your ingest_url (/ingest/YOUR_AMPLITUDE_PROJECT_ID).
404 / empty activity: Confirm YOUR_AMPLITUDE_PROJECT_ID matches the product_id you passed to onboard_product in Step 3, and that you’re querying the same user_id you set via setUserId.
Events in Amplitude Live Events but not landing: Confirm the sync is active and the Event Body template uses event_type (not event_name) inside {"events": [...]}.
No events in Amplitude Live Events: Confirm the sync “Send Events” toggle is on and that you are calling amplitude.setUserId() before tracking events.

👋 Quick Tip: Once you add this code to your site, jump into our Discord and say hi — we will check your data is flowing and help you get fully set up!

📦 What the payload looks like

A sample Amplitude event that Autoplay receives:

{
  "event_type": "$pageview",
  "session_id": 1749012345678,
  "user_id": "user-462718483",
  "device_id": "abc123def456",
  "user_properties": {
    "product_id": "your_product_id",
    "email": "alice@example.com"
  },
  "event_properties": {
    "[Amplitude] Page URL": "https://app.example.com/dashboard",
    "[Amplitude] Page Title": "Dashboard"
  },
  "time": 1749012345678
}

After normalization, ActionsPayload surfaces:

session_id — "1749012345678" (stringified)
user_id — the top-level id from amplitude.setUserId(...) (what the connector keys activity by); email — from user_properties set via amplitude.identify()
actions — extracted page view actions with canonical_url, title, and description

⚠️ Common mistakes

Sending events to the wrong URL. Always point the Amplitude destination at your ingest_url (/ingest/{product_id}) with Authorization: Bearer <ingest_secret>. The product_id lives in the URL path — you don’t set it on the event. Not calling amplitude.setUserId() on login. This is the call that stamps the top-level user_id the connector keys activity by. Without it, events carry only a device_id and your agent can’t find the user by their real id. amplitude.identify() (email / name) is optional enrichment on top. Session ID is −1 in early events. Amplitude initializes session_id to −1 briefly before the first session is established. Autoplay falls back to device_id for these events, which is still a valid scoping key. This is normal and resolves within a few seconds of page load. Not calling amplitude.init() before the chat widget opens. If the chat widget fires GET /sessions/{product_id}/{session_id} before Amplitude’s session is established, there will be no activity to return. Initialize Amplitude at the earliest possible point in your app lifecycle.

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

Choose your AI support agent

Fin (Intercom), Maven, Ada, Botpress, and more — pick yours and connect via MCP.

​⚡ Add this skill

One command

Agent onboarding

Let an AI agent do this for you

​🏁 Before you begin, Create your Amplitude account and project

​🎯 Step 1 — Install the Amplitude SDK in your app

​💻 Step 2 — Initialize on app load

​📝 Step 3 — Register your product with Autoplay

​👤 Step 4 — Identify on login (required for session scoping)

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

​📡 Step 6 — See your activity land

​📦 What the payload looks like

​⚠️ Common mistakes

​🔌 Next: connect your AI support agent

Choose your AI support agent

⚡ Add this skill

🏁 Before you begin, Create your Amplitude account and project

🎯 Step 1 — Install the Amplitude SDK in your app

💻 Step 2 — Initialize on app load

📝 Step 3 — Register your product with Autoplay

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

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

📡 Step 6 — See your activity land

📦 What the payload looks like

⚠️ Common mistakes

🔌 Next: connect your AI support agent