Configure custom session matching

Custom session matching connects replays to sessions that your Amplitude project groups by an event property, such as an order ID. Send that property's value to the replay SDK so an event-based search returns the recording of the same activity.

Use this setup when your project has an event-property session definition. If your project uses the default session_id, Amplitude session matching works automatically. If your pipeline sends no session IDs, configure time-based matching instead.

Prerequisites

Minimum SDK versions

• Browser SDK Plugin: @amplitude/plugin-session-replay-browser version 1.10.0 or later.
• Browser Standalone SDK: @amplitude/session-replay-browser version 1.17.0 or later.
• iOS (plugin and standalone): Session Replay for iOS version 0.11.2 or later.
• Android (plugin and standalone): Session Replay for Android version 0.26.4 or later.

Access and analytics data

• Admin or Manager privileges to edit your project's session definition.
• Analytics events that include a session-defining event property. Use the same property name and session ID value throughout each session.
• The same device ID in your analytics events and replay SDK.

Constraints

• The session replay ID has the format <deviceId>/<sessionId>. Session Replay uses / as a delimiter, so neither deviceId nor custom session ID values can contain /.
• Accepted characters for both deviceId and custom session IDs: a-z A-Z 0-9 _ - . | @ : =.
• If you need an additional character, contact support.

Configure the project and matching option

Configure the project before you update the replay SDK:

1. Go to Settings > Projects and select the project that receives your analytics events.
2. Select Session Definitions, then Custom Session Definition.
3. Under Session property, choose the event property that holds your session ID. Enter the confirmation phrase and select Save. The session definition guide describes additional timeout and start or end event conditions.
4. Go to Organization Settings > Session Replay and select Match Amplitude sessions. This matching option applies to all projects in your organization. Review the session matching options before changing it.

Configure the SDK for custom session definitions

Use the instructions for your platform. Pass the same session ID value to Amplitude and Session Replay, and update the replay SDK whenever your custom session changes.

Browser SDK plugin

Configure the plugin to read the session-defining event property:

1. Install the plugin with the browser plugin quickstart.
2. Add a customSessionId callback to the plugin configuration. Replace your_custom_session_id_property with the event property you selected in Session Definitions.
3. Include that property on the analytics events in your custom session. The callback extracts the value from each event.

import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: 1,
  customSessionId: (event) => {
    const props = event.event_properties;
    if (!props) {
      return;
    }
    const sessionId = props["your_custom_session_id_property"];
    return sessionId;
  },
});
amplitude.add(sessionReplayTracking);

amplitude.init(AMPLITUDE_API_KEY);

The example uses a sample rate of 1 for testing. After verification, restore your production sample rate.

Standalone SDK

The browser standalone SDK accepts the custom ID directly through sessionId:

1. Install the SDK with the standalone quickstart.
2. Read the current session ID from your application or analytics integration. Pass that value as sessionId and the analytics device ID as deviceId when you initialize Session Replay.
3. Send the same session ID as the event property selected in Session Definitions on your analytics events.
4. Call setSessionId with the new value whenever your custom session changes.

import * as sessionReplay from "@amplitude/session-replay-browser";

// Replace these values with IDs from your application or analytics integration.
const deviceId = "your_analytics_device_id";
const sessionId = "your_current_custom_session_id";

await sessionReplay.init(AMPLITUDE_API_KEY, {
  deviceId,
  sessionId,
  sampleRate: 1,
}).promise;

// Call whenever your application starts a new custom session.
await sessionReplay.setSessionId("your_next_custom_session_id").promise;

The example uses a sample rate of 1 for testing. After verification, restore your production sample rate. Refer to Standalone SDK configuration for additional options.

Mobile SDKs

The iOS and Android SDKs accept a string session ID directly instead of a callback:

1. Set customSessionId on iOS or call setCustomSessionId on Android with your current session ID. For initialization and update examples, use Custom session IDs on iOS or Custom session IDs on Android.
2. Send the same value as the session-defining event property to Amplitude.
3. Update the replay SDK with the new value whenever your custom session changes.

Verify custom session matching

1. Capture a test session with a known custom session ID.
2. Check that the test analytics events include the session-defining property and the expected ID value.
3. Find the test replay using an event from that session. Open the replay and confirm that it shows the expected activity.
4. Start another custom session with a different ID and repeat the check. Confirm that the SDK sends the new value.

If the replay doesn't match, compare the session ID and device ID in the analytics events with the values sent to Session Replay. Check the selected project property and matching option.