Session Replay integration with Segment

Session Replay supports other analytics providers. Follow the information below to add Session Replay to an existing Segment-instrumented site.

• Amplitude (Actions) destination
• Amplitude Classic destination (Device-mode)
• Amplitude Classic destination (Cloud-mode)
• Troubleshoot Segment integration

Amplitude (Actions) destination

Amplitude (Actions) tracks sessions automatically. When a user starts a new session, Amplitude sets an analytics_session_id cookie on the users browser. Configure your implementation to listen for changes in value to analytics_session_id, which you can do with Segment's Source Middleware.

This code snippet shows how to configure Session Replay with Segment's Amplitude (Actions) integration, and update the session ID when analytics_session_id changes.

 1import * as sessionReplay from "@amplitude/session-replay-browser";
 2import { AnalyticsBrowser } from "@segment/analytics-next";
 3 
 4const segmentAnalytics = AnalyticsBrowser.load({
 5  writeKey: "segment-key",
 6});
 7 
 8const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment
 9const getStoredSessionId = () => {
10 return cookie.get("amp_session_id") || 0;
11}
12 
13const user = await segmentAnalytics.user();
14const storedSessionId = getStoredSessionId();
15 
16await sessionReplay.init(AMPLITUDE_API_KEY, {
17  sessionId: storedSessionId,
18  deviceId: user.anonymousId()
19}).promise;
20 
21// Add middleware to check if the session id has changed,
22// and update the session replay instance
23segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
24  const storedSessionId = getStoredSessionId();
25  const nextSessionId = payload.obj.integrations['Actions Amplitude'].session_id || 0
26  if (storedSessionId < nextSessionId) {
27    cookie.set("amp_session_id", nextSessionId);
28    sessionReplay.setSessionId(nextSessionId);
29  }
30  next(payload);
31});
32 
33// Add middleware to always add session replay properties to track calls
34SegmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
35  const sessionReplayProperties = sessionReplay.getSessionReplayProperties();
36  if (payload.type() === "track") {
37    payload.obj.properties = {
38      ...payload.obj.properties,
39      ...sessionReplayProperties,
40    };
41  }
42 
43  next(payload);
44});

Amplitude Classic destination (Device-mode)

This version of the Amplitude destination installs the Amplitude JavaScript SDK (5.2.2) on the client, and sends events directly to api.amplitude.com.

The Device-mode integration tracks sessions by default, since it includes the amplitude-js SDK. The included SDK version (5.2.2) doesn't include an event for session changes. As a result, use Segment's middleware to update Session Replay when the session ID changes.

 1import * as sessionReplay from "@amplitude/session-replay-browser";
 2import { AnalyticsBrowser } from "@segment/analytics-next";
 3 
 4const segmentAnalytics = AnalyticsBrowser.load({
 5  writeKey: "segment-key",
 6});
 7 
 8const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment
 9const getAmpSessionId = () => {
10  const sessionId = window.amplitude.getInstance().getSessionId();
11  cookie.set("amp_session_id", sessionId);
12  return sessionId;
13};
14 
15// Wait for the amplitude-js SDK to initialize,
16// then initialize session replay with the correct device id and session id
17window.amplitude.getInstance().onInit(() => {
18  const sessionId = getAmpSessionId();
19  sessionReplay.init(AMPLITUDE_API_KEY, {
20    deviceId: window.amplitude.getInstance().options.deviceId,
21    sessionId: getAmpSessionId(),
22  });
23});
24 
25// Add middleware to check if the session id has changed,
26// and update the session replay instance
27SegmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
28  const nextSessionId = window.amplitude.getInstance().getSessionId();
29  const storedSessionId = cookie.get("amp_session_id") || 0;
30  if (storedSessionId < nextSessionId) {
31    cookie.set("amp_session_id", nextSessionId);
32    sessionReplay.setSessionId(nextSessionId);
33  }
34  next(payload);
35});
36 
37// Add middleware to always add session replay properties to track calls
38SegmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
39  const sessionReplayProperties = sessionReplay.getSessionReplayProperties();
40  if (payload.type() === "track") {
41    payload.obj.properties = {
42      ...payload.obj.properties,
43      ...sessionReplayProperties,
44    };
45  }
46 
47  next(payload);
48});

Amplitude Classic destination (Cloud-mode)

This version of the Amplitude destination sends events to Segment's backend, which forwards them to Amplitude. The Cloud-mode destination doesn't track sessions by default. To overcome this, use the Browser SDK as a shell to manage sessions, and use Session Replay as a plugin, as shown below.

 1import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
 2import { AnalyticsBrowser } from "@segment/analytics-next";
 3 
 4const segmentAnalytics = AnalyticsBrowser.load({
 5  writeKey: "segment-key",
 6});
 7 
 8// A plugin must be added so that events sent through Segment will have
 9// session replay properties and the correct session id
10const segmentPlugin = () => {
11  return {
12    name: "segment",
13    type: "destination",
14    execute: async (event) => {
15      const properties = event.event_properties || {};
16      segmentAnalytics.track(event.event_type, properties, {
17        integrations: {
18          Amplitude: {
19            session_id: amplitude.getSessionId(),
20          },
21        },
22      });
23      return {
24        code: 200,
25        event: event,
26        message: "OK",
27      };
28    },
29  };
30};
31 
32const AMPLITUDE_API_KEY = 'api-key' // must match that saved with Segment
33 
34// Add the session replay plugin first, then the segment plugin
35await amplitude.add(sessionReplayPlugin()).promise;
36await amplitude.add(segmentPlugin()).promise;
37 
38const user = await segmentAnalytics.user();
39await amplitude.init(AMPLITUDE_API_KEY, {
40  instanceName: 'session-replay',
41  sessionTimeout: Number.MAX_SAFE_INTEGER,
42  defaultTracking: false,
43  deviceId: user.anonymousId()
44}).promise;
45amplitude.remove('amplitude');
46// Events must be tracked through the shell Browser SDK to properly attach
47// session replay properties
48amplitude.track('event name')

Troubleshoot Segment integration

Ensure that getSessionReplayProperties() returns a valid value in the format as follows cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244.

The value provided by getSessionReplayProperties() represents the concatenation of deviceId and sessionId in the format ${deviceId}/${sessionId}.

If the instance returns empty, your Segment middleware may not have populated the values for the Amplitude integration field payload.obj.integrations['Actions Amplitude']. If this happens, add the following setTimeout wrapper to ensure this field populate with a valid value.

1SegmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
2    const storedSessionId = getStoredSessionId()
3    setTimeout(() => { 
4      ... // Rest of the Segment integrations code
5    }, 0)
6    next(payload)
7});