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.

ts
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.

ts
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.

ts
sessionReplayPlugin(options?: SessionReplayPluginOptions): SessionReplayPlugin
ts
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).

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.

ts
init(apiKey: string, options: SessionReplayOptions): { promise: Promise<void> }
ts
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.

ts
shutdown(): void

flush

Immediately sends recorded data that's waiting to upload, without waiting for the next batch.

ts
flush(useRetry?: boolean): Promise<void>

Recording

start

Resumes recording after stop(). The sample rate, targeting, and opt-out still apply. Requires 1.49.0 or later.

ts
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.

ts
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).

ts
evaluateTargetingAndCapture(
  targetingParams: {
    event?: Event;
    userProperties?: { [key: string]: any };
    page?: { url?: string };
  },
  isInit?: boolean,
  forceRestart?: boolean,
  forceTargetingReevaluation?: boolean,
): Promise<void>
ts
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.

ts
setSessionId(sessionId: string | number, deviceId?: string): { promise: Promise<void> }
ts
await sessionReplay.setSessionId(1735693200000).promise;

getSessionId

Returns the current session ID.

ts
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().

ts
getSessionReplayProperties(): { [key: string]: boolean | string | null }
ts
sessionReplay.getSessionReplayProperties();
// { "[Amplitude] Session Replay ID": "device-abc123/1735689600000" }

Types

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

Privacy

Recording

Delivery

Performance

Setting performanceConfig replaces the whole default object. If you set only timeout, also set enabled: true.

Logging and debugging

Plugin options

These options exist only on sessionReplayPlugin().

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). The interactionConfig.ugcFilterRules you 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.

이 페이지에서