Configure time-based matching

Time-based matching connects replays to analytics events using device IDs and overlapping time windows. Use it to find the recording around an event when your pipeline sends timestamps without session IDs, such as events delivered through S3.

If your analytics events include session IDs, use Amplitude session matching. If your project groups sessions by an event property, configure custom session matching.

Prerequisites

• Install the Session Replay Standalone SDK in your browser application.
• Send the same device ID to Session Replay and on your analytics events.
• Include event timestamps in your analytics pipeline so Amplitude can match events to replay time windows.

How time-based matching works

Amplitude groups event activity into 30- or 60-minute windows and matches recordings with the same device ID that overlap those windows. The matching has slightly less precision at session boundaries than matching Amplitude sessions.

The standalone SDK still needs a sessionId to group and upload replay data. With time-based matching, you can generate that ID on the frontend. The ID doesn't need to appear on analytics events, but it must be a valid Unix timestamp in milliseconds for the server to accept the upload.

Select the matching window

The organization setting applies to all projects in your organization. Review the matching options before changing it.

1. Go to Organization Settings > Session Replay.
2. Select Time-based event matching.
3. Select a 30- or 60-minute window.
4. Use the same window size for the frontend replay session ID in the SDK setup below.

Set a replay session ID

Configure the standalone SDK with a timestamp-based replay ID:

1. Set WINDOW_MS to 60 * 60 * 1000 for a 60-minute window, or 30 * 60 * 1000 for a 30-minute window.
2. Round the current time down to the start of that window to generate sessionId.
3. Initialize the SDK with that sessionId, your project API key, and the same deviceId your analytics pipeline sends.
4. Call setSessionId when the time window changes. Your application must detect that change; the standalone SDK doesn't manage sessions automatically.

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

const WINDOW_MS = 60 * 60 * 1000;
const now = Date.now();
const sessionId = now - (now % WINDOW_MS);

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

// Run this when your application detects a new time window.
const nextWindowTime = Date.now();
await sessionReplay.setSessionId(nextWindowTime - (nextWindowTime % WINDOW_MS))
  .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.

Verify time-based matching

1. Capture a test session and send a known analytics event during the recording.
2. Check that the analytics event and replay use the same device ID, and that the event timestamp falls within the recorded activity.
3. Find the test replay using that event. Open the replay and confirm that it shows the activity around the event.
4. Test across a time-window boundary. Confirm that your application updates sessionId and continues to capture replay data.

If matching fails, check the device IDs, event timestamps, and the selected organization window. Use Session Replay troubleshooting to diagnose capture and playback failures.