Browser Session Replay reference
このページはまだあなたの言語に翻訳されていません。 現在取り組んでいますので、後でもう一度確認してください。
This reference documents every public export of @amplitude/session-replay-browser (the standalone SDK) and @amplitude/plugin-session-replay-browser (the plugin), and every option they accept. It's verified against @amplitude/session-replay-browser version 1.51.8 and @amplitude/plugin-session-replay-browser version 1.36.7, which depends on that standalone version. For changes in each release, go to the Session Replay Browser SDK release notes.
import * as sessionReplay from "@amplitude/session-replay-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
The standalone SDK exports functions that act on one shared recorder per page. The plugin wraps the standalone SDK: it calls init() for you with IDs and settings from Browser SDK 2, and keeps the session ID in sync. The plugin accepts the standalone options, with the exceptions listed in Plugin options.
Version markers use the standalone version, with the plugin version in parentheses when it differs.
Return values
init(), setSessionId(), and start() return an object with a promise property, which resolves when the call finishes. await the promise before you depend on the result.
await sessionReplay.init("AMPLITUDE_API_KEY", options).promise;
Plugin
sessionReplayPlugin
Creates the plugin. plugin is an alias of the same function. The script-tag build exposes both as window.sessionReplay.plugin and window.sessionReplay.sessionReplayPlugin.
sessionReplayPlugin(options?: SessionReplayPluginOptions): SessionReplayPlugin
| Parameter | Type | Description |
|---|---|---|
options | object | Configuration options, including the plugin options. |
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.1 });
amplitude.add(sessionReplayTracking);
amplitude.init("AMPLITUDE_API_KEY");
SessionReplayPlugin
The class that sessionReplayPlugin() returns. You can also construct it with new SessionReplayPlugin(options).
| Member | Description |
|---|---|
name | "@amplitude/plugin-session-replay-browser". Pass it to amplitude.remove(). |
type | "enrichment". Browser SDK 2 runs the plugin on each event, and the plugin adds the replay ID. |
getSessionReplayProperties() | Same as the standalone getSessionReplayProperties. |
start() | Resumes recording after stop(). Returns a Promise<void>. Requires plugin 1.34.0 or later. |
stop() | Pauses recording and sends what the SDK recorded. Requires plugin 1.34.0 or later. |
sessionReplay | The standalone functions the plugin uses, such as flush() and evaluateTargetingAndCapture(). |
The plugin removes [Amplitude] Session Replay ID from Identify events, and adds it only to events whose session_id is the current session. When the user opts out through Browser SDK 2, the plugin calls shutdown().
Setup
init
Starts the standalone SDK: loads the remote configuration, then starts recording if the SDK selects the session. Calling it again re-applies the options.
init(apiKey: string, options: SessionReplayOptions): { promise: Promise<void> }
| Parameter | Type | Description |
|---|---|---|
apiKey | string | The project's API key. |
options | object | Configuration options. Include deviceId and sessionId. |
await sessionReplay.init("AMPLITUDE_API_KEY", {
deviceId: "device-abc123",
sessionId: 1735689600000,
sampleRate: 0.1,
}).promise;
shutdown
Stops recording, sends what the SDK recorded, and removes the SDK's page listeners. Call init() to start again.
shutdown(): void
flush
Immediately sends recorded data that's waiting to upload, without waiting for the next batch.
flush(useRetry?: boolean): Promise<void>
| Parameter | Type | Description |
|---|---|---|
useRetry | boolean | Retry a failed upload, up to flushMaxRetries. Default false. |
Recording
start
Resumes recording after stop(). The sample rate, targeting, and opt-out still apply. Requires 1.49.0 or later.
start(): { promise: Promise<void> }
stop
Pauses recording and sends what the SDK recorded. The SDK keeps its page listeners, so start() can resume. Requires 1.49.0 or later.
stop(): void
evaluateTargetingAndCapture
Evaluates targeted capture conditions, and starts recording if the session matches. Without a targeting configuration for the project, it does nothing. After a session matches, it stays matched. Requires 1.28.0 or later (plugin 1.22.0).
evaluateTargetingAndCapture(
targetingParams: {
event?: Event;
userProperties?: { [key: string]: any };
page?: { url?: string };
},
isInit?: boolean,
forceRestart?: boolean,
forceTargetingReevaluation?: boolean,
): Promise<void>
| Parameter | Type | Description |
|---|---|---|
targetingParams.event | Event | An analytics event to evaluate, such as { event_type: "Checkout Started" }. |
targetingParams.userProperties | object | The user's properties. |
targetingParams.page.url | string | The page URL. Defaults to window.location.href. |
isInit | boolean | Internal. Default false. |
forceRestart | boolean | Restart recording even when it's already running. Default false. |
forceTargetingReevaluation | boolean | Evaluate again even when the session already matched. Default false. |
await sessionReplay.evaluateTargetingAndCapture({
event: { event_type: "Checkout Started" },
});
Sessions
setSessionId
Starts a new replay for a new session. The SDK sends the previous session's data, fetches the remote configuration again, and restarts recording. Calling it with the current session ID and device ID does nothing.
setSessionId(sessionId: string | number, deviceId?: string): { promise: Promise<void> }
| Parameter | Type | Description |
|---|---|---|
sessionId | string | number | The new session ID. Can't contain /. String IDs require 1.16.0 or later (plugin 1.10.0). |
deviceId | string | Optional. A new device ID. Can't contain /. |
await sessionReplay.setSessionId(1735693200000).promise;
getSessionId
Returns the current session ID.
getSessionId(): string | number | undefined
Replay properties
getSessionReplayProperties
Returns the event properties that link an event to the current replay. Returns {} when the session isn't recording, or before init().
getSessionReplayProperties(): { [key: string]: boolean | string | null }
| Property | Value |
|---|---|
[Amplitude] Session Replay ID | <device ID>/<session ID>. |
[Amplitude] Session Replay Debug | Only when debugMode is true. A JSON string with a hash of the API key, to spot events sent to the wrong project. |
sessionReplay.getSessionReplayProperties();
// { "[Amplitude] Session Replay ID": "device-abc123/1735689600000" }
Types
| Export | Kind | Description |
|---|---|---|
SessionReplayOptions | TypeScript type | Standalone init() options. The plugin package re-exports this type, but the plugin accepts a different set. Go to Plugin options. |
StoreType | TypeScript type | "memory" | "idb". |
AmplitudeSessionReplay | TypeScript type | The shape of the standalone API. |
SendEventsRequest | TypeScript type | { url, method: "POST", headers, body, keepalive }, passed to handleSendEvents. |
FetchConfigRequest | TypeScript type | { url, method: "GET", headers, signal? }, passed to handleFetchConfig. |
SessionReplaySendEventsHandler | TypeScript type | (request: SendEventsRequest) => Promise<Response>. |
SessionReplayFetchConfigHandler | TypeScript type | (request: FetchConfigRequest) => Promise<Response>. |
SafeLoggerProvider | Class | Wraps a logger so a missing method doesn't throw. Standalone only. |
TypeScript types have no runtime value. Import them with import type.
Configuration options
Pass these options to the standalone init() or to sessionReplayPlugin(). The tables mark options that the plugin doesn't accept as Standalone only.
Capture
| Option | Type | Default | Description |
|---|---|---|---|
sampleRate | number | 0 | Fraction of sessions to record, from 0 to 1. 0 records nothing. A sample rate set in Amplitude replaces this value. The SDK hashes the session ID to decide, so all tabs in a session get the same result. Six decimal places require 1.10.0 or later. |
deviceId | string | undefined | The device ID your analytics events use. The SDK doesn't record without it. The plugin reads it from Browser SDK 2, and this option overrides it (plugin 1.13.0 or later). |
sessionId | string | number | undefined | Standalone only. The session ID your analytics events use. The SDK doesn't record without it. String IDs require 1.16.0 or later. |
optOut | boolean | false | Standalone only. true stops recording for this user. If Browser SDK 2 runs on the page with the same instanceName, its opt-out setting wins. |
instanceName | string | "$default_instance" | Standalone only. The Browser SDK 2 instance whose opt-out setting to follow. |
userProperties | object | undefined | Standalone only. User properties for targeted capture when init() runs. Requires 1.28.0 or later. |
Privacy
| Option | Type | Default | Description |
|---|---|---|---|
privacyConfig.defaultMaskLevel | "light" | "medium" | "conservative" | "medium" | What to mask by default. Go to How masking works. A level set in Amplitude replaces this value. Requires 1.6.0 or later (plugin 1.4.0). |
privacyConfig.maskSelector | string[] | undefined | CSS selectors for elements whose text the SDK masks. [data-amp-mask] always applies. Requires 1.6.0 or later (plugin 1.4.0). |
privacyConfig.unmaskSelector | string[] | [".amp-unmask"] | CSS selectors for elements to record even when the level masks them. .amp-unmask and [data-amp-unmask] always apply. Requires 1.6.0 or later (plugin 1.4.0). |
privacyConfig.blockSelector | string | string[] | undefined | CSS selectors for elements to replace with a placeholder. .amp-block and [data-amp-block] always apply. |
privacyConfig.maskAttributes | string[] | undefined | Attribute names to mask on elements whose text the SDK masks. The SDK never masks style. Requires 1.34.0 or later (plugin 1.36.0). |
privacyConfig.urlMaskLevels | { match: string; maskLevel: string }[] | undefined | Standalone only. Mask levels for pages whose URL matches the match pattern. The first match wins. Rules set in Amplitude come first. Requires 1.37.0 or later. |
applyBackgroundColorToBlockedElements | boolean | false | Fills blocked elements with a background color in the replay, so you can see what the SDK blocked. Requires 1.24.0 or later (plugin 1.18.0). |
Recording
| Option | Type | Default | Description |
|---|---|---|---|
shouldInlineStylesheet | boolean | undefined | undefined or true stores stylesheet contents with the recording, so replays don't depend on fetching them later. Set false to store only references. Requires 1.8.0 or later (plugin 1.5.0). |
inlineImages | boolean | false | Stores image data with the recording. Increases upload size. Requires 1.50.0 or later (plugin 1.35.0). |
captureAdoptedStyleSheets | boolean | true | Records stylesheets that scripts attach with adoptedStyleSheets, such as in web components. Requires 1.38.0 or later (plugin 1.28.0). |
enableUrlChangePolling | boolean | false | Also checks the page URL on an interval, for URL changes that history events miss. Requires 1.27.0 or later (plugin 1.21.0). |
urlChangePollingInterval | number | 1000 | Milliseconds between URL checks when enableUrlChangePolling is true. Requires 1.27.0 or later (plugin 1.21.0). |
captureDocumentTitle | boolean | false | Records the page title with each URL change. Requires 1.27.0 or later (plugin 1.21.0). |
crossOriginIframes.enabled | boolean | Off | Records cross-origin iframes that also load Session Replay with crossOriginIframes.enabled set to true. Go to Cross-origin iframe recording. Requires 1.41.0 or later (plugin 1.30.3). |
crossOriginIframes.coordinateChildren | boolean | true | Coordinates recording with child iframes. Requires 1.41.0 or later (plugin 1.30.3). |
fullSnapshotIntervalMs | number | undefined | Standalone only. Milliseconds between full snapshots of the page. When unset, the SDK takes a full snapshot only at the start. Requires 1.42.1 or later. |
eagerFullSnapshotSend | boolean | false | Uploads the first full snapshot right away instead of with the next batch. Requires 1.45.0 or later (plugin 1.32.0). Default changed in 1.46.0. |
captureFullSnapshotOnFocus | boolean | false | Takes a full snapshot when the window gains focus. Requires 1.45.0 or later (plugin 1.32.0). |
Delivery
| Option | Type | Default | Description |
|---|---|---|---|
serverZone | "US" | "EU" | "US" | Standalone only. The data center. "EU" sends to api-sr.eu.amplitude.com and sr-client-cfg.eu.amplitude.com. The plugin reads serverZone from Browser SDK 2. |
trackServerUrl | string | undefined | URL for replay uploads, such as a proxy. Replaces the server-zone endpoint. Requires 1.18.0 or later (plugin 1.11.0). |
configServerUrl | string | undefined | URL for remote configuration. Replaces the server-zone endpoint. The plugin falls back to the Browser SDK 2 remote configuration URL. Requires 1.18.0 or later (plugin 1.11.0). |
storeType | "memory" | "idb" | "memory" | Where unsent data waits. "idb" keeps it in IndexedDB across page loads, and falls back to memory when IndexedDB is unavailable. Default changed in 1.42.0. |
flushMaxRetries | number | 2 | Standalone only. Number of retries for a failed upload. Values above 2 become 2. The plugin reads this value from Browser SDK 2, with the same limit. |
flushIntervalConfig.minIntervalMs | number | 1000 | First upload interval, in milliseconds. The interval grows after each batch. Minimum 100. Requires 1.44.0 or later (plugin 1.31.0). Default changed in 1.46.0. |
flushIntervalConfig.maxIntervalMs | number | 10000 | Longest upload interval, in milliseconds. Accepts Infinity. Requires 1.44.0 or later (plugin 1.31.0). |
sendTimeoutMs | number | 10000 | Milliseconds before an upload request times out and counts as a retryable failure. 0 or less turns the timeout off. Requires 1.45.0 or later (plugin 1.32.0). |
enableTransportCompression | boolean | true | Standalone only. Compresses uploads with gzip when the browser supports CompressionStream. Set false only to debug. Requires 1.44.1 or later. |
maxPersistedEventsSizeBytes | number | 6000000 | Largest batch, in bytes, before the SDK closes and uploads it. From 1000 to 8000000. Requires 1.45.0 or later (plugin 1.32.0). |
maxSingleEventSizeBytes | number | 9000000 | Largest single recorded change, in bytes. The SDK drops larger ones and logs a warning. From 1000 to 10000000. Requires 1.45.0 or later (plugin 1.32.0). |
handleSendEvents | (request: SendEventsRequest) => Promise<Response> | undefined | Sends uploads with your code. The SDK still decides when to retry. Requires 1.47.0 or later (plugin 1.33.0). |
handleFetchConfig | (request: FetchConfigRequest) => Promise<Response> | undefined | Fetches remote configuration with your code. Requires 1.47.0 or later (plugin 1.33.0). |
Performance
| Option | Type | Default | Description |
|---|---|---|---|
useWebWorker | boolean | true | Compresses uploads in a web worker, off the main thread. The worker starts from a blob: URL, so a Content Security Policy needs worker-src blob:. Requires 1.30.0 or later (plugin 1.24.0). Default changed in 1.46.0. |
experimental.useWebWorker | boolean | undefined | Deprecated. Use useWebWorker. |
performanceConfig.enabled | boolean | true | Serializes recorded changes when the browser is idle. Requires 1.14.0 or later (plugin 1.7.0). |
performanceConfig.timeout | number | 2000 | Longest wait, in milliseconds, for idle time before the SDK serializes anyway. Requires 1.14.0 or later (plugin 1.7.0). |
performanceConfig.mergeMutations | boolean | true | Combines page changes that happen close together before upload. Requires 1.39.0 or later (plugin 1.32.0). Default changed in 1.46.0. |
performanceConfig.interaction.timeoutMs | number | undefined | Time limit, in milliseconds, for building the selector of a clicked element. When unset, there's no limit. Requires 1.30.0 or later (plugin 1.25.0). |
performanceConfig.interaction.maxNumberOfTries | number | 10000 | Most attempts when building the selector of a clicked element. Requires 1.30.0 or later (plugin 1.25.0). |
performanceConfig.interaction.threshold | number | 1000 | Element-count threshold for selector building. Requires 1.30.0 or later (plugin 1.25.0). |
Setting performanceConfig replaces the whole default object. If you set only timeout, also set enabled: true.
Logging and debugging
| Option | Type | Default | Description |
|---|---|---|---|
logLevel | number | Upload errors only | Standalone only. 0 none, 1 error, 2 warn, 3 verbose, 4 debug. Without it, the SDK logs upload warnings but not recording decisions. The plugin uses the Browser SDK 2 logLevel. |
loggerProvider | object | Console logger | Standalone only. A logger with log, warn, error, debug, enable, and disable methods, to send SDK messages somewhere else. The plugin uses the Browser SDK 2 loggerProvider. |
debugMode | boolean | false | Adds [Amplitude] Session Replay Debug to the replay properties, to spot events sent to the wrong project. Use it only during setup. |
Plugin options
These options exist only on sessionReplayPlugin().
| Option | Type | Default | Description |
|---|---|---|---|
forceSessionTracking | boolean | false | Turns on Browser SDK 2 Session Start and Session End events, even when autocapture turns them off. Plugin versions before 1.12.1 turned this on by default. |
customSessionId | (event: Event) => string | undefined | undefined | Returns the session ID to record under, for each Browser SDK 2 event. When set, the plugin ignores the Browser SDK 2 session ID. |
The plugin reads sessionId, optOut, serverZone, instanceName, logLevel, loggerProvider, and flushMaxRetries from Browser SDK 2, and doesn't accept them as plugin options. It doesn't accept privacyConfig.urlMaskLevels, fullSnapshotIntervalMs, enableTransportCompression, or userProperties.
Settings managed in Amplitude
The SDK reads these settings only from the remote configuration, and ignores values in code:
- Interaction capture (
interactionConfig.enabled,batch,trackEveryNms). TheinteractionConfig.ugcFilterRulesyou set in code apply only when the project also has interaction settings in Amplitude. Go to Configure UGC filter rules. - Console and network log capture (
loggingConfig). - A minimum session length before upload.
- Targeting conditions. Go to Capture targeted sessions.
The configuration types also include options from the shared Amplitude SDK core, such as flushQueueSize, serverUrl, and transportProvider. Session Replay ignores them.
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.