Session Replay React Native Segment Integration

This article covers how to install Session Replay using the Session Replay React Native Segment plugin. If your React Native app already uses Segment's Analytics React Native library and Amplitude (Actions) destination, use this option.

If you instrument your app with an Amplitude React Native SDK, use the Session Replay React Native SDK Plugin.

If you use Segment with other options, use the standalone implementation.

Before you begin

Use the latest version of the Session Replay React Native Segment Plugin above 0.0.1-beta.2.

The Session Replay React Native Segment Plugin requires that:

1. You build your application with React Native.
2. You use Segment's Analytics React Native library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's Amplitude Session Plugin to extract session IDs.

Quickstart

Install the plugin and its dependencies:

npm install @amplitude/segment-session-replay-plugin-react-native
npm install @amplitude/session-replay-react-native @segment/analytics-react-native

Configure your application code:

import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';
import { createClient } from '@segment/analytics-react-native';
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude-session';

// Initialize Segment client
const segmentClient = createClient({
  writeKey: 'YOUR_SEGMENT_WRITE_KEY',
});

// Configure session replay plugin
const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  deviceId: 'YOUR_DEVICE_ID'
};

// Add the Amplitude session plugin first (required for session ID extraction)
await segmentClient.add({ plugin: new AmplitudeSessionPlugin() });

// Add the session replay plugin to Segment
await segmentClient.add({ plugin: createSegmentSessionReplayPlugin(sessionReplayConfig) });

Configuration

The plugin accepts a SessionReplayConfig object with the following options:

How it works

The Segment Session Replay Plugin automatically:

1. Initializes Session Replay: sets up Amplitude Session Replay with your configuration when you add the plugin to Segment.
2. Syncs session data: updates the session ID and device ID for each Segment event by extracting them from event properties or Amplitude integration data.
3. Enriches events: adds session replay properties to track and screen events before sending them to Segment.
4. Manages lifecycle: handles start and stop operations for session replay based on the plugin lifecycle.

Event processing

The plugin processes the following Segment event types:

• TrackEvent: adds session replay properties to track events.
• ScreenEvent: adds session replay properties to screen events.

For these events, the plugin:

• Extracts the session ID from event properties or Amplitude integration data.
• Extracts the device ID from the event context or anonymous ID.
• Adds session replay properties to the event before sending it to Segment.

Session ID extraction

The plugin extracts session IDs in the following order of priority:

1. From Amplitude integration data: event.integrations['Actions Amplitude'].session_id.
2. From event properties: event.properties.session_id.
3. Defaults to -1 if Amplitude finds no session ID.

Device ID extraction

The plugin extracts device IDs in the following order of priority:

1. From event context: event.context.device.id.
2. From anonymous ID: event.anonymousId.
3. Defaults to null if Amplitude finds no device ID.

Advanced topics

This section provides examples for more advanced use cases.

Manual control

Manually control the session replay plugin after initialization:

import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';

// Create the plugin
const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);

// Add to Segment
await segmentClient.add(sessionReplayPlugin);

// Later, manually control recording
await sessionReplayPlugin.start();
await sessionReplayPlugin.stop();

Custom configuration

For more advanced configurations, pass additional session replay options:

const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  sampleRate: 0.1, // Sample 10% of sessions
  enableRemoteConfig: true,
  logLevel: 4, // Debug level
  autoStart: false, // Don't start automatically
};

const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);

Troubleshooting

Session replay properties not added

If the plugin doesn't add session replay properties to your events:

1. Verify that the Amplitude Session Plugin appears before the Session Replay Plugin.
2. Check that your Segment events are of type track or screen.
3. Confirm that the session replay plugin initializes.

Session ID not found

If the plugin can't extract session IDs:

1. Verify that you configured the Amplitude Session Plugin correctly.
2. Check that you configured the Segment Amplitude destination correctly.
3. Confirm that events include the required Amplitude integration data.

Device ID issues

If device ID extraction fails:

1. Check that your Segment events include device information in the context.
2. Verify that the anonymous ID is set in Segment.
3. Consider manually setting the device ID in the plugin configuration.

For additional troubleshooting, go to the Session Replay React Native SDK Plugin troubleshooting guide.