@amplitude/session-replay-react-native 0.0.1-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AmplitudeSessionReplayReactNative.podspec +45 -0
- package/LICENSE +20 -0
- package/README.md +101 -0
- package/android/build.gradle +101 -0
- package/android/gradle.properties +5 -0
- package/android/src/main/AndroidManifest.xml +3 -0
- package/android/src/main/AndroidManifestNew.xml +2 -0
- package/android/src/main/java/com/amplitude/sessionreplayreactnative/SessionReplayReactNativeModule.kt +182 -0
- package/android/src/main/java/com/amplitude/sessionreplayreactnative/SessionReplayReactNativePackage.kt +17 -0
- package/android/src/main/java/com/amplitude/sessionreplayreactnative/SessionReplayReactNativeViewManager.kt +22 -0
- package/ios/AMPNativeSessionReplay.mm +21 -0
- package/ios/NativeSessionReplay-Bridging-Header.h +2 -0
- package/ios/NativeSessionReplay.swift +150 -0
- package/ios/RCTAmpMaskViewManager.m +29 -0
- package/lib/commonjs/amp-mask-view.js +9 -0
- package/lib/commonjs/amp-mask-view.js.map +1 -0
- package/lib/commonjs/index.js +76 -0
- package/lib/commonjs/index.js.map +1 -0
- package/lib/commonjs/logger.js +42 -0
- package/lib/commonjs/logger.js.map +1 -0
- package/lib/commonjs/native-module.js +31 -0
- package/lib/commonjs/native-module.js.map +1 -0
- package/lib/commonjs/plugin-session-replay-config.js +21 -0
- package/lib/commonjs/plugin-session-replay-config.js.map +1 -0
- package/lib/commonjs/plugin-session-replay.js +150 -0
- package/lib/commonjs/plugin-session-replay.js.map +1 -0
- package/lib/commonjs/session-replay-config.js +49 -0
- package/lib/commonjs/session-replay-config.js.map +1 -0
- package/lib/commonjs/session-replay.js +226 -0
- package/lib/commonjs/session-replay.js.map +1 -0
- package/lib/commonjs/version.js +9 -0
- package/lib/commonjs/version.js.map +1 -0
- package/lib/module/amp-mask-view.js +3 -0
- package/lib/module/amp-mask-view.js.map +1 -0
- package/lib/module/index.js +5 -0
- package/lib/module/index.js.map +1 -0
- package/lib/module/logger.js +35 -0
- package/lib/module/logger.js.map +1 -0
- package/lib/module/native-module.js +25 -0
- package/lib/module/native-module.js.map +1 -0
- package/lib/module/plugin-session-replay-config.js +15 -0
- package/lib/module/plugin-session-replay-config.js.map +1 -0
- package/lib/module/plugin-session-replay.js +144 -0
- package/lib/module/plugin-session-replay.js.map +1 -0
- package/lib/module/session-replay-config.js +40 -0
- package/lib/module/session-replay-config.js.map +1 -0
- package/lib/module/session-replay.js +212 -0
- package/lib/module/session-replay.js.map +1 -0
- package/lib/module/version.js +3 -0
- package/lib/module/version.js.map +1 -0
- package/lib/typescript/amp-mask-view.d.ts +7 -0
- package/lib/typescript/amp-mask-view.d.ts.map +1 -0
- package/lib/typescript/index.d.ts +6 -0
- package/lib/typescript/index.d.ts.map +1 -0
- package/lib/typescript/logger.d.ts +9 -0
- package/lib/typescript/logger.d.ts.map +1 -0
- package/lib/typescript/native-module.d.ts +87 -0
- package/lib/typescript/native-module.d.ts.map +1 -0
- package/lib/typescript/plugin-session-replay-config.d.ts +29 -0
- package/lib/typescript/plugin-session-replay-config.d.ts.map +1 -0
- package/lib/typescript/plugin-session-replay.d.ts +77 -0
- package/lib/typescript/plugin-session-replay.d.ts.map +1 -0
- package/lib/typescript/session-replay-config.d.ts +80 -0
- package/lib/typescript/session-replay-config.d.ts.map +1 -0
- package/lib/typescript/session-replay.d.ts +128 -0
- package/lib/typescript/session-replay.d.ts.map +1 -0
- package/lib/typescript/version.d.ts +2 -0
- package/lib/typescript/version.d.ts.map +1 -0
- package/package.json +96 -0
- package/src/amp-mask-view.tsx +7 -0
- package/src/index.tsx +16 -0
- package/src/logger.ts +41 -0
- package/src/native-module.ts +113 -0
- package/src/plugin-session-replay-config.ts +40 -0
- package/src/plugin-session-replay.ts +159 -0
- package/src/session-replay-config.ts +103 -0
- package/src/session-replay.ts +223 -0
- package/src/version.ts +2 -0
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import { NativeModules, Platform } from 'react-native';
|
|
2
|
+
|
|
3
|
+
const LINKING_ERROR =
|
|
4
|
+
`The package '@amplitude/session-replay-react-native' doesn't seem to be linked. Make sure: \n\n` +
|
|
5
|
+
Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
|
|
6
|
+
'- You rebuilt the app after installing the package\n' +
|
|
7
|
+
'- You are not using Expo Go\n';
|
|
8
|
+
|
|
9
|
+
export const NativeSessionReplay = NativeModules.AMPNativeSessionReplay
|
|
10
|
+
? (NativeModules.AMPNativeSessionReplay as NativeSessionReplaySpec)
|
|
11
|
+
: (new Proxy(
|
|
12
|
+
{},
|
|
13
|
+
{
|
|
14
|
+
get() {
|
|
15
|
+
throw new Error(LINKING_ERROR);
|
|
16
|
+
},
|
|
17
|
+
},
|
|
18
|
+
) as NativeSessionReplaySpec);
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Configuration interface for setting up the native iOS and Android session replay modules.
|
|
22
|
+
* This interface defines all the parameters required to initialize the native session replay functionality.
|
|
23
|
+
*/
|
|
24
|
+
export interface NativeSessionReplayConfig {
|
|
25
|
+
/** Your Amplitude API key for authentication and data routing */
|
|
26
|
+
apiKey: string;
|
|
27
|
+
/** Whether to automatically start recording when the module is initialized */
|
|
28
|
+
autoStart: boolean;
|
|
29
|
+
/** Device identifier that matches the device ID sent with Amplitude events */
|
|
30
|
+
deviceId: string | null;
|
|
31
|
+
/** Whether to enable remote configuration for dynamic settings updates */
|
|
32
|
+
enableRemoteConfig: boolean;
|
|
33
|
+
/** Log level for native module logging (0=None, 1=Error, 2=Warn, 3=Log, 4=Debug) */
|
|
34
|
+
logLevel: 0 | 1 | 2 | 3 | 4;
|
|
35
|
+
/** Level of masking applied to sensitive content in recordings */
|
|
36
|
+
maskLevel: 'light' | 'medium' | 'conservative';
|
|
37
|
+
/** Whether the user has opted out of session replay recording */
|
|
38
|
+
optOut: boolean;
|
|
39
|
+
/** Sample rate for session replay (0.0 to 1.0) determining recording frequency */
|
|
40
|
+
sampleRate: number;
|
|
41
|
+
/** Amplitude server zone for data routing ('US' or 'EU') */
|
|
42
|
+
serverZone: 'US' | 'EU';
|
|
43
|
+
/** Current session identifier for correlating events with recordings */
|
|
44
|
+
sessionId: number;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface NativeSessionReplayProperties {
|
|
48
|
+
[key: string]: string | number | boolean;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Interface defining the native session replay module specification.
|
|
53
|
+
* This interface provides the contract for communication between JavaScript and
|
|
54
|
+
* the native iOS/Android session replay modules through React Native's bridge.
|
|
55
|
+
*
|
|
56
|
+
* All methods are asynchronous and return Promises to handle the bridge communication
|
|
57
|
+
* between JavaScript and native code.
|
|
58
|
+
*/
|
|
59
|
+
export interface NativeSessionReplaySpec {
|
|
60
|
+
/**
|
|
61
|
+
* Flushes any pending session replay data to the server.
|
|
62
|
+
* Forces immediate upload of recorded session data that may be buffered locally.
|
|
63
|
+
*/
|
|
64
|
+
flush(): Promise<void>;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Retrieves the current session identifier from the native module.
|
|
68
|
+
* @returns Promise resolving to the current session ID number
|
|
69
|
+
* @note OLD ARCH: ideally we want to cache that on JS side to avoid bridge overhead
|
|
70
|
+
*/
|
|
71
|
+
getSessionId(): Promise<number>;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Retrieves session replay properties that should be attached to Amplitude events.
|
|
75
|
+
* These properties help correlate events with session recordings.
|
|
76
|
+
* @returns Promise resolving to an object containing session replay metadata
|
|
77
|
+
* @note OLD ARCH: ideally we want to cache that on JS side to avoid bridge overhead
|
|
78
|
+
*/
|
|
79
|
+
getSessionReplayProperties(): Promise<NativeSessionReplayProperties>;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Updates the device identifier used for session replay tracking.
|
|
83
|
+
* @param deviceId - The device identifier string, or null to clear the device ID
|
|
84
|
+
* @note OLD ARCH: combine those into one method to avoid bridge overhead
|
|
85
|
+
*/
|
|
86
|
+
setDeviceId(deviceId: string | null): Promise<void>;
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Updates the session identifier used for session replay tracking.
|
|
90
|
+
* @param sessionId - The session identifier number
|
|
91
|
+
* @note OLD ARCH: combine those into one method to avoid bridge overhead
|
|
92
|
+
*/
|
|
93
|
+
setSessionId(sessionId: number): Promise<void>;
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Initializes the native session replay module with the provided configuration.
|
|
97
|
+
* This method must be called before any other session replay operations.
|
|
98
|
+
* @param config - Configuration object containing all necessary parameters for setup
|
|
99
|
+
*/
|
|
100
|
+
setup(config: NativeSessionReplayConfig): Promise<void>;
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Starts session replay recording.
|
|
104
|
+
* Begins capturing user interactions and screen content for replay.
|
|
105
|
+
*/
|
|
106
|
+
start(): Promise<void>;
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Stops session replay recording.
|
|
110
|
+
* Ends the current recording session and processes any captured data.
|
|
111
|
+
*/
|
|
112
|
+
stop(): Promise<void>;
|
|
113
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { LogLevel } from '@amplitude/analytics-types';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Configuration for Session Replay React Native Plugin
|
|
5
|
+
*/
|
|
6
|
+
export interface SessionReplayPluginConfig {
|
|
7
|
+
/**
|
|
8
|
+
* Sample rate for session replay (0.0 to 1.0)
|
|
9
|
+
* Determines what percentage of sessions will be recorded
|
|
10
|
+
* @default 0
|
|
11
|
+
*/
|
|
12
|
+
sampleRate?: number;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Whether to enable remote configuration
|
|
16
|
+
* @default true
|
|
17
|
+
*/
|
|
18
|
+
enableRemoteConfig?: boolean;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Log level for the SDK
|
|
22
|
+
* @default LogLevel.Warn
|
|
23
|
+
*/
|
|
24
|
+
logLevel?: LogLevel;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Whether to automatically start recording when the plugin is added
|
|
28
|
+
* @default true
|
|
29
|
+
*/
|
|
30
|
+
autoStart?: boolean;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export const getDefaultSessionReplayPluginConfig: () => Required<SessionReplayPluginConfig> = () => {
|
|
34
|
+
return {
|
|
35
|
+
sampleRate: 0,
|
|
36
|
+
enableRemoteConfig: true,
|
|
37
|
+
logLevel: LogLevel.Warn,
|
|
38
|
+
autoStart: true,
|
|
39
|
+
};
|
|
40
|
+
};
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type EnrichmentPlugin,
|
|
3
|
+
type Event,
|
|
4
|
+
type ReactNativeClient,
|
|
5
|
+
type ReactNativeConfig,
|
|
6
|
+
} from '@amplitude/analytics-types';
|
|
7
|
+
|
|
8
|
+
import { SessionReplayPluginConfig, getDefaultSessionReplayPluginConfig } from './plugin-session-replay-config';
|
|
9
|
+
import { getSessionId, getSessionReplayProperties, privateInit, setSessionId, start, stop } from './session-replay';
|
|
10
|
+
import { createSessionReplayLogger } from './logger';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Session Replay Plugin for React Native Amplitude SDK.
|
|
14
|
+
* This plugin automatically handles session replay recording and event correlation.
|
|
15
|
+
*
|
|
16
|
+
* The plugin automatically handles:
|
|
17
|
+
* - Device ID and Session ID management
|
|
18
|
+
* - Session ID changes
|
|
19
|
+
* - Event property collection and tracking
|
|
20
|
+
*/
|
|
21
|
+
export class SessionReplayPlugin implements EnrichmentPlugin<ReactNativeClient, ReactNativeConfig> {
|
|
22
|
+
name = '@amplitude/plugin-session-replay-react-native';
|
|
23
|
+
type = 'enrichment' as const;
|
|
24
|
+
|
|
25
|
+
private config: ReactNativeConfig | null = null;
|
|
26
|
+
private isInitialized = false;
|
|
27
|
+
|
|
28
|
+
private sessionReplayConfig: Required<SessionReplayPluginConfig>;
|
|
29
|
+
private logger = createSessionReplayLogger();
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Create a new Session Replay Plugin instance.
|
|
33
|
+
*
|
|
34
|
+
* @param config - Configuration options for the session replay plugin
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* ```typescript
|
|
38
|
+
* const sessionReplayPlugin = new SessionReplayPlugin({
|
|
39
|
+
* sampleRate: 0.1,
|
|
40
|
+
* enableRemoteConfig: true,
|
|
41
|
+
* logLevel: LogLevel.Warn,
|
|
42
|
+
* autoStart: true
|
|
43
|
+
* });
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
constructor(config: SessionReplayPluginConfig = {}) {
|
|
47
|
+
this.sessionReplayConfig = {
|
|
48
|
+
...getDefaultSessionReplayPluginConfig(),
|
|
49
|
+
...config,
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
this.logger.setLogLevel(this.sessionReplayConfig.logLevel);
|
|
53
|
+
this.logger.log('Creating SessionReplayPlugin with config: ', this.sessionReplayConfig);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Set up the Session Replay Plugin with the Amplitude configuration.
|
|
58
|
+
* This method is called automatically by the Amplitude SDK during initialization.
|
|
59
|
+
*
|
|
60
|
+
* @param config - The React Native configuration from the Amplitude SDK
|
|
61
|
+
* @param _ - The React Native client instance (unused)
|
|
62
|
+
* @returns Promise that resolves when setup is complete
|
|
63
|
+
*/
|
|
64
|
+
async setup(config: ReactNativeConfig, _: ReactNativeClient): Promise<void> {
|
|
65
|
+
this.config = config;
|
|
66
|
+
await privateInit(
|
|
67
|
+
{
|
|
68
|
+
apiKey: config.apiKey,
|
|
69
|
+
deviceId: config.deviceId,
|
|
70
|
+
sessionId: config.sessionId,
|
|
71
|
+
serverZone: config.serverZone as 'EU' | 'US',
|
|
72
|
+
sampleRate: this.sessionReplayConfig.sampleRate,
|
|
73
|
+
enableRemoteConfig: this.sessionReplayConfig.enableRemoteConfig,
|
|
74
|
+
logLevel: this.sessionReplayConfig.logLevel,
|
|
75
|
+
autoStart: this.sessionReplayConfig.autoStart,
|
|
76
|
+
},
|
|
77
|
+
this.logger,
|
|
78
|
+
);
|
|
79
|
+
this.isInitialized = true;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
async execute(event: Event): Promise<Event | null> {
|
|
83
|
+
if (!this.isInitialized) {
|
|
84
|
+
return Promise.resolve(event);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// On event, synchronize the session id to the what's on the browserConfig (source of truth)
|
|
88
|
+
// Choosing not to read from event object here, concerned about offline/delayed events messing up the state stored
|
|
89
|
+
// in SR.
|
|
90
|
+
if (this.config?.sessionId && this.config.sessionId !== (await getSessionId())) {
|
|
91
|
+
await setSessionId(this.config.sessionId);
|
|
92
|
+
}
|
|
93
|
+
// Treating config.sessionId as source of truth, if the event's session id doesn't match, the
|
|
94
|
+
// event is not of the current session (offline/late events). In that case, don't tag the events
|
|
95
|
+
if (this.config?.sessionId && this.config.sessionId === event.session_id) {
|
|
96
|
+
const sessionRecordingProperties = await getSessionReplayProperties();
|
|
97
|
+
event.event_properties = {
|
|
98
|
+
...event.event_properties,
|
|
99
|
+
...sessionRecordingProperties,
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
return Promise.resolve(event);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Start session replay recording.
|
|
107
|
+
* Begins capturing user interactions and screen content for replay.
|
|
108
|
+
*
|
|
109
|
+
* @returns Promise that resolves when recording starts
|
|
110
|
+
*/
|
|
111
|
+
async start(): Promise<void> {
|
|
112
|
+
if (this.isInitialized) {
|
|
113
|
+
await start();
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Stop session replay recording.
|
|
119
|
+
* Ends the current recording session and processes any captured data.
|
|
120
|
+
*
|
|
121
|
+
* @returns Promise that resolves when recording stops
|
|
122
|
+
*/
|
|
123
|
+
async stop(): Promise<void> {
|
|
124
|
+
if (this.isInitialized) {
|
|
125
|
+
await stop();
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
async teardown(): Promise<void> {
|
|
130
|
+
if (this.isInitialized) {
|
|
131
|
+
await stop();
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
this.config = null;
|
|
135
|
+
this.isInitialized = false;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Get session replay properties for manual event correlation.
|
|
140
|
+
* When you send events to Amplitude, call this method to get the most up-to-date session replay properties for the event.
|
|
141
|
+
*
|
|
142
|
+
* @returns Promise that resolves to an object containing session replay metadata
|
|
143
|
+
*
|
|
144
|
+
* @example
|
|
145
|
+
* ```typescript
|
|
146
|
+
* const sessionReplayProperties = await plugin.getSessionReplayProperties();
|
|
147
|
+
* analytics.track('Button Clicked', {
|
|
148
|
+
* buttonName: 'submit',
|
|
149
|
+
* ...sessionReplayProperties
|
|
150
|
+
* });
|
|
151
|
+
* ```
|
|
152
|
+
*/
|
|
153
|
+
async getSessionReplayProperties() {
|
|
154
|
+
if (!this.isInitialized) {
|
|
155
|
+
return {};
|
|
156
|
+
}
|
|
157
|
+
return getSessionReplayProperties();
|
|
158
|
+
}
|
|
159
|
+
}
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { LogLevel } from '@amplitude/analytics-types';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Masking levels for sensitive content in session replay
|
|
5
|
+
*/
|
|
6
|
+
export enum MaskLevel {
|
|
7
|
+
/**
|
|
8
|
+
* Light masking - minimal content is masked
|
|
9
|
+
*/
|
|
10
|
+
Light = 'light',
|
|
11
|
+
/**
|
|
12
|
+
* Medium masking - balanced approach to content masking
|
|
13
|
+
*/
|
|
14
|
+
Medium = 'medium',
|
|
15
|
+
/**
|
|
16
|
+
* Conservative masking - maximum content masking for privacy
|
|
17
|
+
*/
|
|
18
|
+
Conservative = 'conservative',
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Configuration for Session Replay React Native SDK
|
|
23
|
+
*/
|
|
24
|
+
export interface SessionReplayConfig {
|
|
25
|
+
/**
|
|
26
|
+
* Your Amplitude API key
|
|
27
|
+
* @required
|
|
28
|
+
*/
|
|
29
|
+
apiKey: string;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Whether to automatically start recording when the SDK is initialized
|
|
33
|
+
* @default true
|
|
34
|
+
*/
|
|
35
|
+
autoStart?: boolean;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Device identifier that matches the device ID sent with Amplitude events
|
|
39
|
+
* Must match the Device ID passed as event properties to Amplitude
|
|
40
|
+
* @default null
|
|
41
|
+
*/
|
|
42
|
+
deviceId?: string | null;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Whether to enable remote configuration
|
|
46
|
+
* @default true
|
|
47
|
+
*/
|
|
48
|
+
enableRemoteConfig?: boolean;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Log level for the SDK
|
|
52
|
+
* @default LogLevel.Warn
|
|
53
|
+
*/
|
|
54
|
+
logLevel?: LogLevel;
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Level of masking applied to sensitive content
|
|
58
|
+
* @default MaskLevel.Medium
|
|
59
|
+
*/
|
|
60
|
+
maskLevel?: MaskLevel;
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Whether to opt out of session replay collection
|
|
64
|
+
* @default false
|
|
65
|
+
*/
|
|
66
|
+
optOut?: boolean;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Sample rate for session replay (0.0 to 1.0)
|
|
70
|
+
* Determines what percentage of sessions will be recorded
|
|
71
|
+
* @default 0
|
|
72
|
+
*/
|
|
73
|
+
sampleRate?: number;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Server zone for data processing
|
|
77
|
+
* @default 'US'
|
|
78
|
+
* @review: Verify EU server zone compliance and data residency requirements
|
|
79
|
+
*/
|
|
80
|
+
serverZone?: 'EU' | 'US';
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Session identifier that matches the session ID sent with Amplitude events
|
|
84
|
+
* Must match the Session ID passed as event properties to Amplitude
|
|
85
|
+
* @default -1
|
|
86
|
+
*/
|
|
87
|
+
sessionId?: number;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export const getDefaultConfig: () => Required<Omit<SessionReplayConfig, 'apiKey'>> = () => {
|
|
91
|
+
return {
|
|
92
|
+
autoStart: true,
|
|
93
|
+
deviceId: null,
|
|
94
|
+
enableRemoteConfig: true,
|
|
95
|
+
logLevel: LogLevel.Warn,
|
|
96
|
+
maskLevel: MaskLevel.Medium,
|
|
97
|
+
optOut: false,
|
|
98
|
+
sampleRate: 0,
|
|
99
|
+
serverZone: 'US',
|
|
100
|
+
sessionId: -1,
|
|
101
|
+
};
|
|
102
|
+
};
|
|
103
|
+
export { LogLevel };
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
// @refresh reset
|
|
2
|
+
|
|
3
|
+
import { NativeSessionReplay, type NativeSessionReplayConfig } from './native-module';
|
|
4
|
+
import { getDefaultConfig, SessionReplayConfig } from './session-replay-config';
|
|
5
|
+
import { createSessionReplayLogger } from './logger';
|
|
6
|
+
import { VERSION } from './version';
|
|
7
|
+
|
|
8
|
+
let fullConfig: Required<SessionReplayConfig> | null = null;
|
|
9
|
+
let isInitialized = false;
|
|
10
|
+
let logger = createSessionReplayLogger();
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Configure the SDK and begin collecting replays.
|
|
14
|
+
* This function must be called before any other session replay operations.
|
|
15
|
+
*
|
|
16
|
+
* @param config - Configuration object containing API key, device ID, session ID, and other options
|
|
17
|
+
* @returns Promise that resolves when initialization is complete
|
|
18
|
+
* @throws Error if initialization fails
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* ```typescript
|
|
22
|
+
* await init({
|
|
23
|
+
* apiKey: 'YOUR_API_KEY',
|
|
24
|
+
* deviceId: 'user-device-id',
|
|
25
|
+
* sessionId: Date.now(),
|
|
26
|
+
* sampleRate: 0.1
|
|
27
|
+
* });
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
export async function init(config: SessionReplayConfig): Promise<void> {
|
|
31
|
+
if (isInitialized) {
|
|
32
|
+
logger.warn('SessionReplay is already initialized');
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
fullConfig = {
|
|
37
|
+
...getDefaultConfig(),
|
|
38
|
+
...config,
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
logger.setLogLevel(fullConfig.logLevel);
|
|
42
|
+
logger.log(`initializing @amplitude/session-replay-react-native version: ${VERSION} with config: `, fullConfig);
|
|
43
|
+
|
|
44
|
+
try {
|
|
45
|
+
await NativeSessionReplay.setup(nativeConfig(fullConfig));
|
|
46
|
+
logger.log('SessionReplay initialized');
|
|
47
|
+
isInitialized = true;
|
|
48
|
+
} catch (error) {
|
|
49
|
+
logger.error('Error initializing SessionReplay', error);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Call whenever the session ID changes.
|
|
55
|
+
* The Session ID you pass to the SDK must match the Session ID sent as event properties to Amplitude.
|
|
56
|
+
*
|
|
57
|
+
* @param sessionId - The new session identifier number
|
|
58
|
+
* @returns Promise that resolves when the session ID is updated
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* ```typescript
|
|
62
|
+
* await setSessionId(Date.now());
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
65
|
+
export async function setSessionId(sessionId: number): Promise<void> {
|
|
66
|
+
if (!isInitialized) {
|
|
67
|
+
logger.warn('SessionReplay is not initialized');
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
await NativeSessionReplay.setSessionId(sessionId);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Update the device ID used for session replay tracking.
|
|
75
|
+
* The Device ID you pass to the SDK must match the Device ID sent as event properties to Amplitude.
|
|
76
|
+
*
|
|
77
|
+
* @param deviceId - The device identifier string, or null to clear the device ID
|
|
78
|
+
* @returns Promise that resolves when the device ID is updated
|
|
79
|
+
*
|
|
80
|
+
* @example
|
|
81
|
+
* ```typescript
|
|
82
|
+
* await setDeviceId('user-device-id');
|
|
83
|
+
* // or clear device ID
|
|
84
|
+
* await setDeviceId(null);
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
87
|
+
export async function setDeviceId(deviceId: string | null): Promise<void> {
|
|
88
|
+
if (!isInitialized) {
|
|
89
|
+
logger.warn('SessionReplay is not initialized');
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
await NativeSessionReplay.setDeviceId(deviceId);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Get the current session identifier from the session replay SDK.
|
|
97
|
+
*
|
|
98
|
+
* @returns Promise that resolves to the current session ID number, or null if not initialized
|
|
99
|
+
*
|
|
100
|
+
* @example
|
|
101
|
+
* ```typescript
|
|
102
|
+
* const sessionId = await getSessionId();
|
|
103
|
+
* if (sessionId !== null) {
|
|
104
|
+
* console.log('Current session ID:', sessionId);
|
|
105
|
+
* }
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
export async function getSessionId(): Promise<number | null> {
|
|
109
|
+
if (!isInitialized) {
|
|
110
|
+
logger.warn('SessionReplay is not initialized');
|
|
111
|
+
return null;
|
|
112
|
+
}
|
|
113
|
+
return await NativeSessionReplay.getSessionId();
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Interface for session replay properties that should be attached to Amplitude events.
|
|
118
|
+
* These properties help correlate events with session recordings.
|
|
119
|
+
*/
|
|
120
|
+
export interface SessionReplayProperties {
|
|
121
|
+
[key: string]: string | boolean | null;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* When you send events to Amplitude, call this function to get the most up-to-date session replay properties for the event.
|
|
126
|
+
* Collect Session Replay properties to send with other event properties.
|
|
127
|
+
*
|
|
128
|
+
* @returns Promise that resolves to an object containing session replay metadata
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```typescript
|
|
132
|
+
* const sessionReplayProperties = await getSessionReplayProperties();
|
|
133
|
+
* analytics.track('Button Clicked', {
|
|
134
|
+
* buttonName: 'submit',
|
|
135
|
+
* ...sessionReplayProperties // Merge session replay properties
|
|
136
|
+
* });
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
139
|
+
export async function getSessionReplayProperties(): Promise<SessionReplayProperties> {
|
|
140
|
+
if (!isInitialized) {
|
|
141
|
+
logger.warn('SessionReplay is not initialized');
|
|
142
|
+
return {};
|
|
143
|
+
}
|
|
144
|
+
const properties = await NativeSessionReplay.getSessionReplayProperties();
|
|
145
|
+
return properties as SessionReplayProperties;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Flush any pending session replay data to the server.
|
|
150
|
+
* Forces immediate upload of recorded session data that may be buffered locally.
|
|
151
|
+
*
|
|
152
|
+
* @returns Promise that resolves when the flush operation is complete
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```typescript
|
|
156
|
+
* // Flush data before app termination
|
|
157
|
+
* await flush();
|
|
158
|
+
* ```
|
|
159
|
+
*/
|
|
160
|
+
export async function flush(): Promise<void> {
|
|
161
|
+
if (!isInitialized) {
|
|
162
|
+
logger.warn('SessionReplay is not initialized');
|
|
163
|
+
return;
|
|
164
|
+
}
|
|
165
|
+
await NativeSessionReplay.flush();
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Start session replay recording.
|
|
170
|
+
* Begins capturing user interactions and screen content for replay.
|
|
171
|
+
* If autoStart is enabled in the configuration, this is called automatically during initialization.
|
|
172
|
+
*
|
|
173
|
+
* @returns Promise that resolves when recording starts
|
|
174
|
+
*
|
|
175
|
+
* @example
|
|
176
|
+
* ```typescript
|
|
177
|
+
* // Start recording manually if autoStart is false
|
|
178
|
+
* await start();
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
181
|
+
export async function start(): Promise<void> {
|
|
182
|
+
if (!isInitialized) {
|
|
183
|
+
logger.warn('SessionReplay is not initialized');
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
await NativeSessionReplay.start();
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* Stop session replay recording.
|
|
191
|
+
* Ends the current recording session and processes any captured data.
|
|
192
|
+
*
|
|
193
|
+
* @returns Promise that resolves when recording stops
|
|
194
|
+
*
|
|
195
|
+
* @example
|
|
196
|
+
* ```typescript
|
|
197
|
+
* // Stop recording when user logs out or app goes to background
|
|
198
|
+
* await stop();
|
|
199
|
+
* ```
|
|
200
|
+
*/
|
|
201
|
+
export async function stop(): Promise<void> {
|
|
202
|
+
if (!isInitialized) {
|
|
203
|
+
logger.warn('SessionReplay is not initialized');
|
|
204
|
+
return;
|
|
205
|
+
}
|
|
206
|
+
await NativeSessionReplay.stop();
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
function nativeConfig(config: Required<SessionReplayConfig>): NativeSessionReplayConfig {
|
|
210
|
+
return {
|
|
211
|
+
...config,
|
|
212
|
+
logLevel: config.logLevel as NativeSessionReplayConfig['logLevel'],
|
|
213
|
+
maskLevel: config.maskLevel.toString() as NativeSessionReplayConfig['maskLevel'],
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
export async function privateInit(
|
|
218
|
+
config: SessionReplayConfig,
|
|
219
|
+
newLogger: ReturnType<typeof createSessionReplayLogger>,
|
|
220
|
+
): Promise<void> {
|
|
221
|
+
logger = newLogger;
|
|
222
|
+
return init(config);
|
|
223
|
+
}
|
package/src/version.ts
ADDED