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

One command

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

CLI

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

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

View the skill →

Prerequisite: install the SDK first — see Quickstart.

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 — see Amplitude’s getting-started docs for account/project setup — then come back here.

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

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.

---

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

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

npm install @amplitude/unified

📺 Full setup walkthrough

---

💻 Step 2 — Verify initialization and autocapture

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.

Your app should already call amplitude.initAll() once at startup (main.ts, _app.tsx, or root layout) — see Amplitude’s browser SDK docs for the general init pattern and where to find your API key if you need to check it.

📺 Copy your Amplitude API key

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

 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.

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

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

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

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="[e-mail]",  # 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.

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.

---

⚙️ 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

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 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:

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

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.

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

Choose your AI support agent

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