---
title: Configure custom session matching
description: "Match replays to a custom session-defining event property in your Amplitude project."
product: session-replay
lang: en
token_estimate: 1806
---
# Configure custom session matching

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

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](https://amplitude.com/docs/session-replay/session-matching#match-amplitude-sessions-recommended) works automatically. If your pipeline sends no session IDs, [configure time-based matching](https://amplitude.com/docs/session-replay/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](https://amplitude.com/docs/data/sources/instrument-track-sessions#configure-a-custom-session-definition) 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](https://amplitude.com/docs/session-replay/session-matching#choose-a-matching-option) 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](https://amplitude.com/docs/sdks/session-replay/session-replay-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.

```javascript
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](https://amplitude.com/docs/session-replay/configure-sampling).

### Standalone SDK

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

1. Install the SDK with the [standalone quickstart](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#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.

```javascript
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](https://amplitude.com/docs/session-replay/configure-sampling). Refer to [Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-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](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#custom-session-ids) or [Custom session IDs on Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone#custom-session-ids).
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](https://amplitude.com/docs/session-replay/verify-capture#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](https://amplitude.com/docs/session-replay/find-replays) 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](https://amplitude.com/docs/session-replay/session-matching#configure-session-matching).