@amplitude/segment-session-replay-plugin-react-native 0.0.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Amplitude Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @amplitude/segment-session-replay-plugin-react-native
+
+Amplitude Segment Session Replay Plugin for React Native
+
+## Installation
+
+```sh
+npm install @amplitude/segment-session-replay-plugin-react-native
+```
+
+### Dependencies
+
+This plugin requires the following dependencies to be installed:
+
+```sh
+npm install @amplitude/session-replay-react-native @segment/analytics-react-native
+```
+
+**Important**: This plugin requires the `@segment/analytics-react-native-plugin-amplitude-session` plugin to extract session IDs from Amplitude integration data. Make sure to add this plugin to your Segment client **before** adding the session replay plugin.
+
+## Usage
+
+### Segment Session Replay Plugin
+
+Add the segment session replay plugin to your Segment Analytics instance to automatically integrate Amplitude Session Replay with your Segment events.
+
+```js
+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(createSegmentSessionReplayPlugin(sessionReplayConfig));
+```
+
+### Plugin Configuration
+
+The plugin accepts a `SessionReplayConfig` object
+
+### Automatic Integration
+
+The plugin automatically:
+
+1. **Initializes Session Replay**: Sets up Amplitude Session Replay with your configuration
+2. **Syncs Session Data**: Updates session ID and device ID for each Segment event
+3. **Enriches Events**: Adds session replay properties to track and screen events
+4. **Manages Lifecycle**: Handles start/stop operations for session replay
+
+### 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 session ID from event properties or Amplitude integration data
+- Extracts device ID from event context or anonymous ID
+- Adds session replay properties to the event before sending to Segment
+

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@amplitude/segment-session-replay-plugin-react-native",
+  "version": "0.0.1-beta.2",
+  "description": "Amplitude Segment Session Replay Plugin for React Native",
+  "keywords": [
+    "analytics",
+    "amplitude",
+    "react-native",
+    "ios",
+    "android",
+    "session-replay"
+  ],
+  "author": "Amplitude Inc",
+  "homepage": "https://github.com/amplitude/Amplitude-TypeScript",
+  "license": "MIT",
+  "main": "lib/commonjs/index",
+  "module": "lib/module/index",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amplitude/Amplitude-TypeScript.git"
+  },
+  "scripts": {
+    "build": "bob build",
+    "fix": "yarn fix:eslint & yarn fix:prettier",
+    "fix:eslint": "eslint '{src,test}/**/*.ts' --fix",
+    "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
+    "lint": "yarn lint:prettier && yarn lint:eslint",
+    "lint:eslint": "eslint '{src,test}/**/*.ts'",
+    "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"",
+    "test": "jest",
+    "typecheck": "tsc -p ./tsconfig.json",
+    "version": "yarn version-file && yarn build",
+    "version-file": "node -p \"'export const VERSION = \\'' + require('./package.json').version + '\\';'\" > src/version.ts",
+    "typescript": "tsc --noEmit"
+  },
+  "files": [
+    "src",
+    "!test",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "bugs": {
+    "url": "https://github.com/amplitude/Amplitude-TypeScript/issues"
+  },
+  "devDependencies": {
+    "@amplitude/session-replay-react-native": ">=0.0.1-beta.2 <1.0.0",
+    "@segment/analytics-react-native": "2.15.0",
+    "react-native-builder-bob": "^0.20.3"
+  },
+  "peerDependencies": {
+    "@amplitude/session-replay-react-native": "*",
+    "@segment/analytics-react-native": ">= 2.2.0 < 3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "gitHead": "1ff69489af101b6a8780786b54a1caf403a4a425"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { createSegmentSessionReplayPlugin } from './segment-session-replay-plugin';

package/src/segment-session-replay-plugin.ts

@@ -0,0 +1,93 @@
+import { Plugin, PluginType, type SegmentEvent, EventType, SegmentClient } from '@segment/analytics-react-native';
+
+import {
+  type SessionReplayConfig,
+  getSessionReplayProperties,
+  init,
+  setDeviceId,
+  setSessionId,
+  start,
+  stop,
+} from '@amplitude/session-replay-react-native';
+import { VERSION } from './version';
+
+function getSessionId(event: SegmentEvent): number {
+  const amplitudeSessionId =
+    (event.integrations?.['Actions Amplitude'] as { session_id: number })?.['session_id'] ?? null;
+  if (amplitudeSessionId !== null) {
+    return amplitudeSessionId;
+  }
+
+  if (event.type === EventType.TrackEvent || event.type === EventType.ScreenEvent) {
+    const sessionIdRaw = event.properties?.['session_id'];
+    const sessionId = Number(sessionIdRaw);
+    return Number.isNaN(sessionId) ? -1 : sessionId;
+  }
+  return -1;
+}
+
+function getDeviceId(event: SegmentEvent): string | null {
+  return event.context?.device?.id ?? event.anonymousId ?? null;
+}
+
+export class SegmentSessionReplayPlugin extends Plugin {
+  name = 'amplitude-segment-session-replay-plugin-react-native';
+  version: string = VERSION;
+  type: PluginType = PluginType.enrichment;
+
+  private sessionReplayConfig: SessionReplayConfig;
+
+  // @review: This is to ensure the plugin is initialized before the first event is processed.
+  // because `configure` is not asynchronous
+  private initPromise: Promise<void> | null = null;
+
+  constructor(config: SessionReplayConfig) {
+    super();
+    this.sessionReplayConfig = config;
+  }
+
+  async configure(analytics: SegmentClient): Promise<void> {
+    super.configure(analytics);
+    this.initPromise = init({
+      deviceId: analytics.userInfo.get().anonymousId,
+      ...this.sessionReplayConfig,
+    });
+    await this.initPromise;
+  }
+
+  async execute(event: SegmentEvent): Promise<SegmentEvent> {
+    await this.initPromise;
+
+    const sessionId = getSessionId(event);
+    const deviceId = getDeviceId(event);
+
+    await setSessionId(sessionId);
+    await setDeviceId(deviceId);
+
+    if (event.type === EventType.TrackEvent || event.type === EventType.ScreenEvent) {
+      const properties = await getSessionReplayProperties();
+      event.properties = { ...event.properties, ...properties };
+    }
+
+    return event;
+  }
+
+  async shutdown(): Promise<void> {
+    await this.initPromise;
+    await stop();
+  }
+
+  async start(): Promise<void> {
+    await this.initPromise;
+    await start();
+  }
+
+  async stop(): Promise<void> {
+    await this.initPromise;
+    await stop();
+  }
+}
+
+export function createSegmentSessionReplayPlugin(config: SessionReplayConfig): Plugin {
+  return new SegmentSessionReplayPlugin(config);
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = '0.0.1-beta.2';