Get started with Browser Session Replay
이 페이지는 아직 귀하의 언어로 번역되지 않았습니다. 현재 작업 중이므로 곧 다시 확인해 주십시오.
This guide installs Session Replay on a website, records one test session, and confirms the replay in Amplitude. Session Replay is off until you install it and set a sample rate. Each step lists the conditions that commonly stop replays at that step, so you can fix a problem where it happens. For every option, go to Configuration options. For changes in each release, go to the Session Replay Browser SDK release notes.
Choose a variant
Session Replay for the browser ships in two packages. Install one of them, not both.
| Variant | Use it when | Package |
|---|---|---|
| Plugin | The site sends events with Browser SDK 2. | @amplitude/plugin-session-replay-browser |
| Standalone SDK | The site sends events with another analytics tool, such as Segment or Google Analytics, or with a server. | @amplitude/session-replay-browser |
The plugin reads the device ID, session ID, opt-out setting, and server zone from Browser SDK 2. The standalone SDK reads nothing from other tools: you pass it the device ID and session ID that your analytics tool sends with its events. Amplitude uses those IDs to match each replay to the user's events. For the options, go to Choose a session matching option.
For a new Amplitude installation, use the Browser Unified SDK (@amplitude/unified) instead. It includes Browser SDK 2 and the Session Replay plugin in one package.
Prerequisites
- An Amplitude project and its API key. Find the key in Settings > Projects > your project > General.
- The data center your organization uses: US (default) or EU.
- A Session Replay plan. Your organization shares one replay quota across projects.
- For the plugin, Browser SDK 2 installed on the page. For the standalone SDK, a device ID and session ID from your analytics tool, available in the browser.
- A page served over
http://orhttps://, in a browser that Amplitude SDKs support.
Install the SDK
Choose one installation method for your variant.
npm install @amplitude/plugin-session-replay-browser
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
To serve the script from your own domain, go to Self-host the browser Session Replay script.
Fix installation problems
| Symptom | Cause | Fix |
|---|---|---|
net::ERR_BLOCKED_BY_CLIENT for the script or upload requests | An ad blocker or privacy extension blocks Amplitude domains. | Bundle the SDK from npm, and send uploads through a proxy. Test in a profile without extensions. |
Cannot read properties of undefined (reading 'plugin'), or (reading 'init') (script tag) | Your code runs before the script loads, or a Content Security Policy blocks cdn.amplitude.com. | Load the script before code that uses window.sessionReplay, and add https://cdn.amplitude.com to script-src. |
Initialize the SDK
Set sampleRate explicitly. It defaults to 0, which records no sessions. The examples use 1 to record every session while you test. Lower it before you release, or set the rate in Amplitude, which overrides the code.
Add the plugin before you call init(), so it records from the first page load.
amplitude.add(sessionReplayPlugin({ sampleRate: 1 }));
amplitude.init("AMPLITUDE_API_KEY");
With the script tag, use the global:
<script>
window.amplitude.add(window.sessionReplay.plugin({ sampleRate: 1 }));
window.amplitude.init("AMPLITUDE_API_KEY");
</script>
If your project uses the EU data center, set serverZone: "EU" in the Browser SDK 2 init() options. The plugin reads serverZone from Browser SDK 2.
Initialize Session Replay only in browser code. With server-side rendering, initialize it from a client entry point or an effect, not from code that also runs on the server.
Fix initialization problems
| Symptom | Cause | Fix |
|---|---|---|
Debug log: Opting session <id> out of recording due to sample rate. | sampleRate is 0 (the default), or the rate didn't select this session. | Set sampleRate: 1 while you test. Check the rate in Session Replay settings, which overrides the code. |
Debug log: Session <id> not being captured due to capture being disabled for project or because the remote config could not be fetched. | The SDK couldn't load its remote configuration, or capture is off for the project. Session Replay doesn't record without it. | Allow sr-client-cfg.amplitude.com (or sr-client-cfg.eu.amplitude.com) in connect-src and in any proxy or firewall. Check that capture is on in Session Replay settings. |
Debug log: Session is not being recorded due to lack of session id. (or device id) | Standalone only. init() didn't receive a sessionId or deviceId. | Pass both to init(). Read them from your analytics tool after it initializes. |
Debug log: Opting session <id> out of recording due to optOut config. | Opt-out is on: the Browser SDK 2 optOut setting for the plugin, or the optOut option for the standalone SDK. | Opt the user back in, or test in a fresh browser profile. |
Uploads go to api-sr.amplitude.com for a project in the EU data center | serverZone isn't set to EU. | Set serverZone: "EU" for EU projects. Omit it for US projects. |
To see these log lines, turn on debug logging.
Record a test session
- Open a page where Session Replay runs.
- Click, type, and scroll for about a minute. Navigate to a second page if your site has one.
- Send at least one analytics event during the session. With the plugin, a Browser SDK 2 page view counts. With the standalone SDK, send it from your analytics tool with the same device ID and session ID you passed to Session Replay.
The SDK uploads recorded data in batches while the user interacts, and when the user hides or leaves the page. A page with no activity sends nothing until the next interaction.
Fix upload problems
| Symptom | Cause | Fix |
|---|---|---|
Console error containing Content Security Policy for api-sr.amplitude.com | The site's Content Security Policy blocks the upload endpoint. | Add the Session Replay endpoints to connect-src. Go to Allow Session Replay in a Content Security Policy. |
No requests to /sessions/v2/track in the Network tab | The SDK didn't select the session for recording, or the page has had no activity since the last batch. | Check the debug log for the reasons in Fix initialization problems, then interact with the page. |
Debug log: Session replay event batch rejected due to exceeded retry count | Uploads failed with a network or server error, and the SDK stopped retrying. | Open the failed request in the Network tab. A request blocked by the browser needs a CSP or proxy fix. For a server error, check the API key and serverZone. |
| Replays upload, but the replay doesn't open from the user's events | The device ID or session ID on the events differs from the one Session Replay used. | Go to Check that the replay matches its session. |
Confirm a replay in Amplitude
- In Amplitude, open User Lookup and search for the device ID or user ID from your test session.
- Open the session in the Activity tab, and select Play Session.
- Confirm that the replay shows the clicks and page changes you made.
Replays usually appear in Amplitude about five minutes after the session starts. If the replay doesn't appear, follow Verify replays, which checks each stage between the page and Amplitude.
Next steps
- Choose what to mask or block before you record real users.
- Lower the sample rate for production.
- Allow Session Replay in your Content Security Policy or send it through a proxy.
이 내용이 도움이 되었나요?
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.