Session matching

Session Replay matches replays to Amplitude data to provide a complete view of the user journey. Session matching links device and session information from Session Replay to Amplitude sessions.

Session Replay offers multiple session matching options. Choose the option that works best for your technical constraints and session definitions.

Session matching options

Amplitude provides options to match sessions directly, match events based on time, or match by Amplitude session ID.

Match Amplitude sessions (recommended)

Match Amplitude sessions based on your project's session definition. Amplitude session matching respects how you configure sessions in your Amplitude project settings, including sessions you define with event properties, timeout windows, or start/end events.

If you use the default session_id, Session Replay works automatically with no additional configuration.

If you use a custom session property, configure the Session Replay SDK to extract and send that same property value. Session Replay then matches sessions using your project's custom session definition, which provides the most accurate alignment between replay data and analytics sessions.

Requirements for custom session definitions

Minimum SDK versions:

• Browser SDK Plugin: @amplitude/plugin-session-replay-browser version 1.10.0 or later.
• Standalone SDK: @amplitude/session-replay-browser version 1.17.0 or later.

Project configuration:

• Configure your custom session definition in Settings > Projects > Session Definitions.
• Use the "Counted based on <> Property" option to define sessions by a specific property.
• For more details, refer to Track sessions.

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 SDK for custom session definitions

The following code examples apply only if you configured a custom session definition in your Amplitude project settings.

Browser SDK Plugin:

Pass a method that extracts the custom session ID from Amplitude events:

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

const sessionReplayTracking = sessionReplayPlugin({
  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);

Standalone SDK:

The standalone SDK treats custom session IDs and timestamp-based session IDs the same way. Pass the session ID to the standalone SDK, and send that same session ID to Amplitude as an event property that matches your project's custom session definition:

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

// Initialize Session Replay with session ID
sessionReplay.init(AMPLITUDE_API_KEY, {
  customSessionId: (event) => {
    const props = event.event_properties;
    if (!props) {
      return;
    }
    const sessionId = props["your_custom_session_id_property"];
    return sessionId;
  },
});

Ensure the session ID property name matches the property configured in your project's custom session definition (Settings > Projects > Session Definitions).

Time-based event matching

Build sessions using 30- or 60-minute time windows based on event activity. Use time-based event matching if you can't send a session ID from your frontend due to technical or architectural constraints.

Time-based matching is slightly less precise than true session matching, but still delivers a reliable and useful journey view.

Session ID matching (legacy)

Match based on the Amplitude session_id, even if the session_id doesn't align with custom session definitions. Session ID matching exists for backward compatibility and requires no changes.

Choose a matching option

Match Amplitude sessions whenever possible, including custom session definitions, as long as you send the same session ID to both Amplitude and Session Replay.

If you can't send session IDs from your frontend, use time-based event matching.

Configure session matching

Configure session matching at the organization level, not at the project level. Configure your session matching option in Organization Settings > Session Replay. For more information, refer to Session Replay and Heatmap Settings.

To configure session matching in your Session Replay SDK implementation, the exact steps depend on which SDK you use:

• Browser SDK Plugin: Refer to Session Replay Browser SDK Plugin for configuration details.
• Standalone SDK: Refer to Session Replay Standalone SDK for configuration details.
• Mobile SDKs: Refer to the relevant mobile SDK documentation for your platform.

When using custom session IDs, ensure the Session Replay SDK sends the same session ID value that you use in Amplitude, so that sessions match correctly.

Session matching changes are quick and reversible. You can change your matching option at any time without losing data.

Frequently asked questions

Does session matching require re-instrumentation?

Usually no. If you use custom sessions, ensure the Session Replay SDK sends the same session ID value already used in Amplitude.

What are the tradeoffs with time-based matching?

Time-based matching has slightly less precision at session boundaries, but still provides a clear and actionable view of the user journey.

Can I change the matching option later?

Yes. You can change session matching quickly, and you can fully reverse the change.

Does changing the matching option affect historical data?

You don't lose any data. The change impacts how Amplitude matches and views replays going forward.

Is Amplitude deprecating session ID matching?

No. Amplitude continues to support session ID matching, though Amplitude recommends newer options for most use cases.