세션 리플레이 브라우저 SDK 플러그인
세션 리플레이 계측
세션 리플레이는 기본적으로 켜져 있지 않으며 표준 Amplitude 계측 이상의 설정이 필요합니다.
세션 리플레이 Browser SDK 플러그인은 이미 Amplitude Browser SDK 2로 계측된 사이트에 세션 녹화를 추가합니다. 사이트에서 이미 Amplitude 계측을 사용하고 있다면 이 옵션을 사용하십시오. 제품 내 분석을 위해 Amplitude 이외의 공급자를 사용하는 경우, 독립형 구현을 선택하십시오. 브라우저 SDK에 대한 자세한 내용은 브라우저 SDK 2를 참조하세요.
세션 리플레이 및 성능 세션
리플레이는 다음 방법으로 설치된 웹 페이지의 성능에 미치는 영향을 최소화합니다.
- 효율적인 압축과 최적화된 번들 크기를 위해 웹후크를 통해 비동기적으로 콘텐츠를 처리합니다.
- 요청을 일괄 처리하고 경량 압축을 사용하여 네트워크 연결과 대역폭을 줄입니다.
- DOM 처리 최적화.
번들 크기
세션 리플레이 플러그인은 애플리케이션의 번들 크기를 늘립니다.
현재 번들 크기 정보는 npm 패키지 페이지 또는 BundlePhobia를 확인하세요.
런타임 성능
세션 리플레이는 비동기식으로 실행되며 기본 스레드를 차단하지 않도록 백그라운드에서 재생 데이터를 처리합니다. 성능 특성은 다음과 같습니다.
- DOM 캡처: DOM 스냅샷 캡처는 일반적으로 각 페이지 상호 작용에 대해 5ms 미만의 처리 시간을 추가합니다. 초기 페이지 로드 스냅샷 캡처는 페이지의 복잡성에 따라 10~50ms 정도 걸릴 수 있습니다.
- 메모리 사용량: 세션 리플레이는 재생 이벤트를 메모리 또는 IndexedDB에 저장합니다(
storeType를 사용하여 구성 가능). 메모리 사용량은 세션 길이와 페이지 복잡성에 따라 증가하며, 일반적으로 각 활성 세션에 대해 1~10MB의 범위입니다. - CPU 영향: 기본 설정을 사용하면 세션 리플레이가 정상적인 작동 중에 CPU 시간을 2% 미만으로 사용합니다. 세션 리플레이는
performanceConfig.enabled이true인 경우(기본값) 브라우저 유휴 기간으로 압축 작업을 연기합니다. - 네트워크 대역폭: 세션 리플레이는 업로드 전에 재생 데이터를 압축하므로 일반적으로 페이로드 크기를 60~80% 줄입니다. 세션 리플레이는 네트워크 요청을 일괄 처리하여 비동기적으로 전송합니다.
성능 최적화
세션 리플레이 성능을 최적화하려면 다음을 수행하십시오.
useWebWorker을 활성화하면, 압축이 메인 스레드에서 벗어나 CPU에 미치는 영향을 줄입니다.- 지연된 압축이 발생할 시기를 제어하도록
performanceConfig.timeout구성합니다. - 페이지 재로드 시 지속성이 필요하지 않은 경우
storeType으로 설정하여 IndexedDB 오버헤드를 줄입니다memory.
자세한 성능 테스트 결과는 세션 리플레이 성능 테스트 블로그 게시물을 참조하십시오.
세션 리플레이는 섀도우 DOM의 요소를 포함하여 페이지의 문서 객체 모델(DOM)에 대한 변경 사항을 캡처합니다. 그런 다음 세션 리플레이는 이러한 변경 사항을 재생하여 비디오와 유사한 재생을 구성합니다. 예를 들어, 세션이 시작될 때 세션 리플레이는 페이지의 DOM에 대한 전체 스냅샷을 캡처합니다. 사용자가 페이지와 상호작용할 때, 세션 리플레이는 DOM에 대한 각 변경 사항을 차이로 캡처합니다. 세션의 재생을 시청할 때, 세션 리플레이는 각 차이를 순차적으로 원본 DOM에 다시 적용하여 재생을 구성합니다. 세션 리플레이에는 최대 길이가 없습니다.
서버측 렌더링 및 하이드레이션
Next.js, Nuxt, SvelteKit, Angular SSR 및 React Router와 같은 프레임워크는 서버에서 HTML을 렌더링한 다음 브라우저에서 하이드레이션합니다. 레코더는 문서가 구문 분석을 완료할 때까지 기다린 다음 서버에서 렌더링된 HTML의 전체 스냅샷을 생성합니다. 세션 리플레이는 하이드레이션 중에 프레임워크가 수행하는 모든 DOM 변경 사항을 증분 변경으로 기록하므로 리플레이는 사용자가 각 시점에서 본 것을 보여줍니다.
세션 리플레이는 브라우저에서만 실행됩니다. 플러그인을 추가하고 서버에서도 실행되는 코드가 아닌 클라이언트 전용 코드(예: 클라이언트 엔트리 useEffect파일, 훅, onMount콜백)init에서 이를 호출하십시오.
SDK 초기화 지연
페이지가 로드될 때까지 세션 리플레이 초기화를 연기하면 페이지 로드 지표에 대한 SDK의 기여도가 제거됩니다. Time to Interactive 또는 Largest Contentful Paint와 같은 로드 시간 지표를 측정해야 하고 세션 리플레이의 영향이 0이 되기를 원할 때 이 접근 방식을 사용하십시오. 조기 초기화를 유지하면서 영향을 줄이려는 것이 목표인 경우 대신 성능 최적화의 구성 옵션을 사용하십시오.
평소와 같이 Amplitude를 초기화하고 load이벤트 리스너를 사용하여 세션 리플레이 플러그인만 연기하십시오.
import * as amplitude from "@amplitude/analytics-browser";
// Initialize Amplitude at page load as usual
amplitude.init(API_KEY);
// Load and add the Session Replay plugin only after the page has fully loaded
window.addEventListener('load', async () => {
const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
await amplitude.add(sessionReplayTracking).promise;
});
또는 requestIdleCallback를 사용하여 브라우저가 유휴 상태가 될 때까지 연기합니다. 이 접근 방식은 활동이 적은 순간을 기다리므로 다른 로드 후 작업과의 경합이 줄어듭니다.
import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(API_KEY);
requestIdleCallback(async () => {
const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
await amplitude.add(sessionReplayTracking).promise;
});
세션 리플레이는 초기화 시 전체 DOM 스냅샷을 캡처합니다. 초기화 전에 발생한 상호작용은 재생에 나타나지 않습니다.
Angular 앱
Zone.js를 사용하는 Angular 앱에서 Browser SDK 2 Angular 가이드에 설명된 것과 동일한 방식으로 플러그인을 추가하고 Angular 영역 init외부에서 호출하십시오. 예를 들어, bootstrapApplication 전에 main.ts에서 두 가지를 모두 호출하십시오.
// main.ts
import { bootstrapApplication } from "@angular/platform-browser";
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";
amplitude.add(sessionReplayPlugin({ sampleRate: 1 }));
amplitude.init(AMPLITUDE_API_KEY);
bootstrapApplication(AppComponent, appConfig);
레코더는 이미 브라우저의 패치가 적용되지 않은 MutationObserver를 사용하므로 DOM 변형 추적은 Zone.js를 통해 실행되지 않습니다. 마우스, 스크롤 및 입력 리스너와 같은 레코더의 이벤트 리스너는 Zone.js를 통해 실행됩니다. 레코더가 Angular 영역 내에서 시작되는 경우, 각 기록된 이벤트는 Angular 변경 감지를 트리거합니다.
전제 조건
세션 리플레이 플러그인을 사용하려면 다음이 필요합니다.
- 귀하의 애플리케이션은 웹 기반입니다.
- SDK에 장치 ID를 제공할 수 있습니다.
- 귀하의 사이트는 브라우저 2.0 SDK를 사용합니다.
지원되는 브라우저
세션 리플레이는 Amplitude의 SDK와 동일한 브라우저 세트를 지원합니다. 자세한 내용은 브라우저 호환성을 참조하십시오.
세션 리플레이는 브라우저 확장 기능 중 일부나 브라우저 확장 기능이 도입한 DOM 요소를 지원하지 않을 수도 있습니다.
세션 리플레이는 섀도우 DOM을 지원하지만 사이트에서 사용하는 프레임워크에 따라 예외가 있을 수 있습니다.
빠른 시작
플러그인을 npm 또는 yarn으로 설치하세요.
Amplitude를 처음 사용하시나요? 통합 SDK 사용
브라우저 SDK를 아직 설치하지 않은 경우, 브라우저 통합 SDK(@amplitude/unified)를 사용하십시오. 분석 및 기능 실험과 함께 단일 패키지에 세션 리플레이가 포함됩니다. 두 패키지를 모두 설치하는 대신 하나의 패키지 진입점을 선택합니다.
# New integration: install the Unified SDK (includes Session Replay)
npm install @amplitude/unified
# Existing Browser SDK integration: add the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save
애플리케이션 코드를 구성합니다.
import { initAll } from "@amplitude/unified";
// Initialize Unified SDK with Session Replay enabled
initAll("YOUR_API_KEY", {
sessionReplay: {
sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
},
});
또한 해당 코드를 사이트의 <head>에 직접 추가할 수도 있습니다. 이 방법을 사용하면 애플리케이션이 다른 곳에서 브라우저 SDK를 초기화하지 않도록 해야 합니다. 브라우저 SDK를 두 번 이상 초기화하면 장치 ID 또는 세션 ID가 일치하지 않을 수 있습니다.
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.49.3-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.37.0-min.js.gz"></script>
<script>
// sampleRate: 1 records 100% of sessions for initial testing; lower this for production. The SDK default (0) records nothing.
const sessionReplayTracking = window.sessionReplay.plugin({ sampleRate: 1 });
window.amplitude.add(sessionReplayTracking);
window.amplitude.init(API_KEY);
</script>
세션 리플레이 계측은 Amplitude 프로젝트의 맥락에서 발생합니다. Amplitude는 조직 수준에서 리플레이 할당량을 정의합니다. 따라서 여러 프로젝트에 걸쳐 여러 세션 리플레이 구현을 가질 수 있으며, 각 프로젝트는 고유한 샘플링 속도를 갖고 동일한 할당량에서 데이터를 수집할 수 있습니다.
태그 관리자와의 호환성: 세션 리플레이 플러그인 스크립트는 페이지의 <head>태그에 추가할 때 비동기적으로 로드됩니다. 결과적으로 이 구현은 Google 태그 관리자와 호환되지 않습니다. 자세한 내용은 Google 태그 관리자를 사용한 세션 리플레이 구현을 참조하세요.
구성
| 이름 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
sampleRate | number | 아니요 | 0 | 리플레이 수집을 위해 선택할 세션 수를 제어합니다. 숫자는 0과 1 사이의 소수입니다. 예를 들어 0.4는 Amplitude가 재생 수집을 위해 무작위로 선택한 세션의 비율을 나타냅니다. 많은 수의 세션 중에서 0.4는 해당 세션의 40%을 선택합니다. 세션 리플레이는 샘플링 속도를 포함한 설정의 원격 구성을 지원하기 때문에 이 필드는 필수가 아닙니다. |
privacyConfig | object | 아니요 | undefined | CSS 선택기를 사용하여 고급옵션 마스킹 구성을 지원합니다. |
applyBackgroundColorToBlockedElements | boolean | 아니요 | false | true인 경우 시각적 마스킹을 위해 차단된 요소에 배경색을 적용합니다. 이를 통해 세션 리플레이가 캡처를 차단하는 요소를 확인할 수 있습니다. |
debugMode | boolean | 아니요 | false | API 키의 해시가 포함된 [Amplitude] Session Replay Debug이벤트 속성을 추가하여 앱 불일치와 같은 계측 문제를 디버깅하는 데 도움이 됩니다. 초기 설정을 디버깅할 때만 권장되며 프로덕션에는 권장되지 않습니다. |
serverZone | string | 아니요 | US | EU 또는 US. Amplitude 서버 영역을 설정합니다. EU 데이터 센터의 Amplitude 프로젝트에 대해서는 이 값을 EU로 설정하십시오. |
configServerUrl | string | 아니요 | undefined | 원격 구성을 가져올 엔드포인트 URL입니다. 제공된 경우, 기본 서버 영역 구성을 재정의합니다. |
trackServerUrl | string | 아니요 | undefined | 세션 리플레이 데이터를 전송하기 위한 엔드포인트 URL입니다. 제공된 경우, Amplitude는 기본 세션 리플레이 엔드포인트 대신 SDK의 요청을 해당 위치로 전달합니다. |
shouldInlineStylesheet | boolean | 아니요 | true | true인 경우 세션 리플레이는 인라인 스타일시트의 내용을 저장합니다. 재생 중에 세션 리플레이는 원격으로 가져오는 대신 저장된 스타일시트를 사용합니다. 이렇게 하면 스타일시트가 누락되어 재생이 끊어진 것으로 나타나는 것을 방지할 수 있습니다. 인라이닝 스타일시트는 모든 경우에 작동하지 않을 수 있습니다. 정의되지 않은 경우 세션 리플레이는 스타일시트를 인라이닝합니다. |
storeType | string | 아니요 | idb | 세션 리플레이가 재생 이벤트를 저장하는 방법. idb세션 리플레이가 캡처 중에 모든 이벤트를 전송할 수 없는 경우 IndexedDB를 사용하여 재생 이벤트를 유지합니다. memory재생 이벤트를 메모리에만 저장하므로 페이지가 닫힐 때 이벤트가 손실됩니다. IndexedDB를 사용할 수 없는 경우 시스템은 메모리로 폴백합니다. |
performanceConfig.enabled | boolean | 아니요 | true | 활성화된 경우 세션 리플레이는 브라우저의 유휴 다음 기간동안 이벤트 압축이 발생하도록 지연합니다. |
performanceConfig.timeout | number | 아니요 | undefined | requestIdleCallback API에 대한 선택적 시간 초과(밀리초)입니다. 이 값을 지정하면 브라우저가 유휴 상태가 아니더라도 지연된 압축 작업을 실행하기 전에 브라우저가 대기할 최대 시간을 설정합니다. |
useWebWorker | boolean | 아니요 | false | 웹 워커를 사용하여 재생 이벤트를 압축합니다. 이렇게 하면 메인 스레드에서 압축을 제거하여 성능이 향상됩니다. |
API 엔드포인트
브라우저 SDK와 플러그인은 다음 엔드포인트를 사용합니다. Amplitude 프로젝트와 일치하는 지역을 선택합니다.
| 목적 | 미국 | EU |
|---|---|---|
| 리플레이 데이터 수집 | https://api-sr.amplitude.com/sessions/v2/track | https://api-sr.eu.amplitude.com/sessions/v2/track |
| 원격 구성 | https://sr-client-cfg.amplitude.com/config | https://sr-client-cfg.eu.amplitude.com/config |
도메인 프록시를 설정한 경우 요청을 이러한 엔드포인트로 전달하십시오. trackServerUrl 및 configServerUrl로 기본값을 재정의합니다.
대체 API 엔드포인트
브라우저 SDK 네트워크 가이드라인에는 다음과 같은 엔드포인트 제품군도 포함됩니다. 이러한 주소로 요청을 전송하는 구현의 경우 프록시 및 CSP 구성에 해당 도메인을 포함하십시오.
| 목적 | 미국 | EU |
|---|---|---|
| 리플레이 데이터 수집 | https://api-secure.amplitude.com/sessions/track | https://api.eu.amplitude.com/sessions/track |
| 원격 구성 | https://api-secure.amplitude.com/sessions/config | https://api.eu.amplitude.com/sessions/config |
기본 세션 이벤트 추적
세션 리플레이는 기본적으로 세션 추적을 활성화합니다. 이를 통해 세션 리플레이는 세션 시작 및 세션 종료 이벤트를 캡처합니다. 세션 리플레이를 구현하기 전에 이러한 이벤트를 캡처하지 않았다면 이벤트 볼륨이 증가할 것으로 예상됩니다. 세션 추적에 대한 자세한 내용은 브라우저 SDK 2.0 | 세션 추적을 참조하십시오.
브라우저 SDK 구성을 사용하여 세션 추적을 암시적으로 활성화합니다.
amplitude.init(API_KEY, USER, {
autocapture: {
sessions: true,
},
});
세션 시작 및 세션 종료 이벤트
플러그인 버전 1.12.1부터 세션 리플레이는 더 이상 기본적으로 Session End이벤트를 캡처하지 않습니다Session Start. 이러한 이벤트를 캡처할 수 있도록 설정하려면 forceSessionTracking: true:
const sessionReplayTracking = window.sessionReplay.plugin({
forceSessionTracking: true, // Enable capture of Session Start and Session End events
sampleRate: 1, // 100% sample rate, should reduce for production traffic.
});
Amplitude는 리플레이 재생을 활성화하기 위해 캡처된 전체 세션에 최소 하나의 이벤트가 필요합니다.
단일 페이지 앱 탐색
세션 리플레이는 새 페이지를 로드하지 않는 변경 사항을 포함하여 변경 될 때마다 페이지 URL을 기록합니다. 레코더는 history.pushState및 history.replaceState를 감싸고 popstate및 hashchange이벤트를 수신합니다. 이러한 변경 사항 중 하나라도 발생하면location.href, 세션 리플레이는 재생에 새 URL을 기록합니다.
여기에는 앱이 SvelteKit의 경로나 pushState의 $app/navigation 또는 Next.js Pages Router의 와 같은 경로 변경 없이 URL을 업데이트하는 얕은 라우팅이 포함됩니다router.push(url, undefined, { shallow: true }). 리플레이는 얕은 경로가 변경된 후의 모든 것을 새 URL로 지정합니다. 히트맵은 각 클릭이 발생할 location.href때 의 URL을 사용하므로 얕은 경로 변경 후 클릭은 새 URL로 계산됩니다.
예를 들어 스크립트가 세션 리플레이에서 감싸지 않은 히스토리 메서드를 호출하기 때문에 세션 리플레이가 URL 변경을 놓친 경우, enableUrlChangePolling로 true설정하십시오. 그런 다음 세션 리플레이는 기록 이벤트를 관찰하는 대신 특정 location.href간격으로 확인합니다. urlChangePollingInterval를 사용하여 간격을 밀리초 단위로 설정합니다. 기본값은 1000입니다.
const sessionReplayTracking = sessionReplayPlugin({
enableUrlChangePolling: true,
urlChangePollingInterval: 1000,
});
화면상의 데이터 마스킹
세션 리플레이 SDK는 사용자 입력, 텍스트 및 기타 HTML 요소를 마스킹하는 세 가지 방법을 제공합니다.
| 요소 | 설명 |
|---|---|
<input> | 세션 리플레이는 기본적으로 모든 텍스트 입력 필드를 마스킹합니다. 사용자가 입력 필드에 텍스트를 입력하면 세션 리플레이는 텍스트 대신 별표를 캡처합니다. 텍스트 입력의 마스킹을 해제하려면 .amp-unmask 클래스를 추가하십시오. 예를 들어: <input class="amp-unmask">. |
| 텍스트 | 비입력 요소 내에서 텍스트를 마스크하려면 .amp-mask 클래스를 추가하십시오. 예를 들어, <p class="amp-mask">Text</p>. 마스크된 상태에서 세션 리플레이는 마스킹된 텍스트를 일련의 별표로 캡처합니다. |
| 비텍스트 요소 | 텍스트가 아닌 요소를 차단하려면 .amp-block 클래스를 추가하십시오. 예를 들어, <div class="amp-block"></div>. 세션 리플레이는 차단된 요소를 동일한 치수의 자리 표시자로 바꿉니다. |
세션 리플레이 개인정보 보호 설정에서 Light, Medium 또는 Conservative 마스킹 및 원격 재정의를 구성합니다. 원격 설정이 SDK 설정과 충돌할 때 우선합니다.
구성 중에 privacyConfig 객체에서 차단하거나 마스킹할 요소를 지정합니다.
// This configuration blocks .no-track and #ads, sets the default mask level,
// and defines the mask and unmask selectors.
await sessionReplay.init(AMPLITUDE_API_KEY, {
privacyConfig: {
blockSelector: ['.no-track', '#ads'],
defaultMaskLevel: 'medium',
maskSelector: ['.sensitive-data', '.user-email'],
unmaskSelector: ['.public-info', '#main-content']
}
}).promise;
CSS 선택기
세션 리플레이의 구성은 다양한 유형의 CSS 선택기를 지원합니다. 요소 태그(h1 또는 textarea), 클래스 이름(.hidden) 또는 데이터 속성을 지정합니다.
데이터 속성은 해싱 때문에 클래스 이름이 자주 변경되는 경우 유용할 수 있습니다. 데이터 속성을 사용하려면 data-amp-unmask또는 data-amp-mask같은 사용자 지정 속성을 HTML 요소에 추가하십시오. 예를 들어, <textarea data-amp-unmask></textarea>와 같은 경우처럼 선택기를 지정할 때 속성을 대괄호[data-amp-unmask]로 묶습니다.
원격 구성
원격 구성을 활성화했지만 로드하지 못할 경우 세션 리플레이는 세션을 캡처하지 않습니다. 이렇게 하면 Admin 인터페이스에서 정의한 개인정보 보호 설정 없이 캡처가 방지됩니다.
사용자 옵트아웃
세션 리플레이 플러그인은 브라우저 SDK의 optOut설정을 따르며 사용자 옵트아웃을 자체적으로 지원하지 않습니다.
콘텐츠 보안 정책(CSP)
웹 애플리케이션이 엄격한 콘텐츠 보안 정책을 사용하는 경우, 구현이 API 엔드포인트에서 사용하는 도메인을 허용하십시오.
필수 CSP 지시어
CDN 로딩을 위해 script-src, 수집 및 원격 구성을 위해 connect-src, 그리고 useWebWorker를 활성화한 경우 worker-src를 추가합니다.
CSP 지시어 참조
| 지시어 | 도메인 | 요구 사항 |
|---|---|---|
script-src | https://cdn.amplitude.com | Amplitude의 CDN에서 브라우저 SDK 또는 플러그인을 로드할 때 필수입니다. |
connect-src | https://api-sr.amplitude.com 그리고 https://sr-client-cfg.amplitude.com | US 리플레이 수집 및 원격 구성. |
connect-src | https://api-sr.eu.amplitude.com 그리고 https://sr-client-cfg.eu.amplitude.com | serverZone: "EU"인 경우 EU 리플레이 수집 및 원격 구성. |
connect-src | https://api-secure.amplitude.com | 대체 US API 엔드포인트를 사용하는 구현에 필요합니다. |
connect-src | https://api.eu.amplitude.com | 대체 EU API 엔드포인트를 사용하는 구현에 필요합니다. |
worker-src | blob: | useWebWorker 리플레이 이벤트 압축을 활성화한 경우 필수입니다. |
CSP 헤더 예제
US 수집 및 원격 구성의 경우:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.amplitude.com https://sr-client-cfg.amplitude.com; worker-src 'self' blob:;
EU 수집 및 원격 구성의 경우:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.eu.amplitude.com https://sr-client-cfg.eu.amplitude.com; worker-src 'self' blob:;
대체 미국 엔드포인트를 사용하는 구현의 경우:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;
대체 EU 엔드포인트를 사용하는 구현의 경우:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;
configServerUrl 또는 trackServerUrl를 사용하여 사용자 지정 엔드포인트를 지정하는 경우, 해당 기본 도메인 대신 connect-src에 해당 도메인을 추가하십시오.
EU 데이터 상주
세션 리플레이는 EU 데이터 센터를 사용하는 Amplitude 고객에게 제공됩니다. 초기화 중에 serverZone 구성 옵션을 EU(으)로 설정하십시오. 예를 들면 다음과 같습니다.
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
serverZone: "EU", // [tl! ~~]
}).promise;
샘플링 속도
기본적으로 세션 리플레이는 재생을 위해 세션의 0%를 캡처합니다. Amplitude의 새로운 계정 스니펫을 사용하여 계측한 경우, 샘플링 비율은 테스트를 더 쉽게 하기 위해 기본값으로 1(세션의 100%)으로 설정됩니다. [세션 리플레이] 설정 페이지에서 샘플링 속도를 업데이트하거나 sampleRate구성 옵션을 사용하여 세션 리플레이가 캡처하는 총 세션의 비율을 설정하십시오. 예를 들면 다음과 같습니다.
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
sampleRate: 0.01,
}).promise;
수동 및 동적 샘플링, 할당량 계획 및 remote-setting 우선 순위를 확인하려면 세션 리플레이 샘플링 구성으로 이동하십시오.
리플레이 수집 비활성화
세션 리플레이를 활성화한 후에는 다음 중 하나가 발생할 때까지 사이트에서 실행됩니다.
- 사용자가 귀하의 사이트를 떠납니다.
amplitude.remove(sessionReplayTracking.name)을(를) 호출하십시오.
이 예제에서는 초기화 코드에서 변수를 사용한다고 sessionReplayTracking가정합니다.
사용자가 사이트의 제한된 영역으로 이동하기 전에 amplitude.remove('sessionReplayTracking')를 호출하여 사용자가 해당 영역에 있는 동안 리플레이 수집을 비활성화하십시오.
재생 수집을 다시 시작하려면 amplitude.add(sessionReplayTracking)를 호출하여 플러그인을 다시 추가하십시오.
amplitude.add() 는 유형의 객체를 Plugin매개변수로 사용하고 문자열을 매개변수로 사용합니다. amplitude.remove()이 매개변수는 제거하려는 플러그인의 이름입니다.
을 호출하기 전에 항상 amplitude.add()가 완료될 때까지 기다리십시오amplitude.remove(). 그렇지 않으면 콘솔에 다음과 같은 오류가 발생할 수 있습니다TypeError: Cannot read properties of undefined (reading 'teardown'). 이 두 예제 중 하나에 표시된 것처럼, 이 작업을 수행하려면 promise속성을 사용하십시오.
await amplitude.add(sessionReplayTracking).promise;
await amplitude.remove(sessionReplayTracking.name).promise;
const addPromise = amplitude.add(sessionReplayTracking).promise;
addPromise.then(() => {
amplitude.remove(sessionReplayTracking.name).promise;
});
또한 Amplitude 실험과 같은 기능 플래그 제품을 사용하여 위치와 같은 기준에 따라 리플레이 수집을 활성화하거나 비활성화하는 로직을 만들 수도 있습니다. 예를 들어, 특정 사용자 그룹을 대상으로 하는 기능 플래그를 생성하고 이를 초기화 논리에 추가합니다.
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);
if (nonEUCountryFlagEnabled) {
// Create and Install Session Replay Plugin
const sessionReplayTracking = sessionReplayPlugin({
sampleRate: 0.5,
});
amplitude.add(sessionReplayTracking);
}
데이터 리텐션
세션 리플레이는 개인정보 보호 및 삭제 요청에 Amplitude 도구와 API를 사용합니다. 캡처를 구현할 때 동의 지침을 검토하십시오.
리텐션 기간
기본 리텐션, 확장 리텐션 및 리텐션 변경 발효일에 대해서는 세션 리플레이 데이터 생애주기 참조로 이동하십시오.
DSAR API
세션 리플레이 데이터 생애주기 분석 참조는 DSAR API가 반환하는 메타데이터를 설명합니다.
데이터 삭제
사용자 및 프로젝트 삭제 동작을 보려면 세션 리플레이 데이터 삭제로 이동하십시오.
봇 필터
봇 필터링 및 속성 필터 제한을 보려면 세션 리플레이 봇 필터링으로 이동하십시오.
세션 리플레이 스토리지
세션 리플레이는 사용자의 브라우저에 쿠키를 설정하지 않습니다. 대신, 기본적으로 IndexedDB라는 브라우저 스토리지 옵션에 의존합니다. 이 옵션은 사용자가 브라우저 탭을 탐색하거나 탭을 닫았다가 다시 연 세션 중에 지속적인 재생 수집을 활성화합니다. SDK는 IndexedDB에 저장된 데이터를 정리하며 사용자의 디스크 공간에 영향을 주지 않습니다.
환경이 IndexedDB를 지원하지 않는 경우 세션 리플레이는 인메모리 스토리지 옵션으로 폴백됩니다. 인메모리 스토리지는 내구성이 떨어지며 사용자가 브라우저 창을 닫을 때 데이터가 손실됩니다. config 옵션을 storeType 'memory'로 설정하여 인메모리 스토리지를 강제로 적용합니다.
사용자가 사이트의 모든 쿠키를 거부하는 경우, optOut 구성 옵션을 사용하여 해당 사용자에 대해 리플레이 수집을 비활성화하십시오.
IndexedDB 모범 사례
IndexedDB가 초기화되고 제대로 작동하는지 확인하려면 다음을 수행하십시오.
CSP 헤더를 검토하여 지나치게 제한적이지 않도록 하십시오.
default-src및script-src지시어가 필요한 소스를 허용하는지 확인합니다.동일한 오리진 내에서 IndexedDB 작업을 수행합니다. 교차 오리진 제한 사항은 IndexedDB 작업을 차단할 수 있습니다.
사용자가 IndexedDB를 지원하는 최신 브라우저를 사용하는지 확인하십시오. Amplitude는 최신 버전의 Chrome, Firefox, Safari, Edge 또는 Opera를 권장합니다.
쿠키
세션 리플레이는 쿠키를 직접 사용하지 않으며 쿠키 크기에 영향을 미치지 않습니다. 브라우저 SDK는 세션 관리를 위해 쿠키를 사용합니다.
알려진 제한 사항
세션 리플레이를 구현할 때 다음과 같은 제한 사항에 유의하십시오.
- 세션 리플레이는 여러 프로젝트에 걸쳐 단일 사용자의 재생을 함께 연결하지 않습니다. 예를 들면 다음과 같습니다.
- 마케팅 사이트와 웹 애플리케이션을 각각 세션 리플레이가 활성화된 별도의 Amplitude 프로젝트로 계측합니다.
- 알려진 사용자가 마케팅 사이트에서 시작하여 웹 애플리케이션에 로그인합니다.
- Amplitude는 두 세션을 모두 캡처합니다.
- 각 세션의 재생이 호스트 프로젝트에 나타납니다.
- 세션 리플레이는 다음 HTML 요소를 캡처할 수 없습니다.
- 캔버스
- WebGL.
objectFlash, Silverlight 또는 Java와 같은 플러그인을 포함하는 태그. 세션 리플레이는object type="image"<iframe>을 지원합니다.- Lottie 애니메이션.
- crossorigin
<iframe>속성으로 세션 리플레이 SDK를 로드하지 않는 교차 출처 <iframe> 요소crossOriginIframes.enabled: true(예: Stripe 또는 Google Maps와 같은 타사 임베드). 퍼스트파티 교차 출처 iframe을 캡처하려면 교차 출처 iframe 녹화로 이동하세요. - 글꼴, CSS 또는 이미지와 같이 인증이 필요한 자산입니다.
- 세션 리플레이는 광고 차단 소프트웨어와 호환되지 않습니다.
여러 Amplitude 인스턴스
세션 리플레이는 Amplitude SDK의 단일 인스턴스에 연결할 수 있도록 지원합니다. 응용 프로그램에서 두 개 이상의 인스턴스를 사용하는 경우 프로젝트와 가장 관련성이 높은 인스턴스에서 세션 리플레이를 시작해야 합니다.
<script>
const sessionReplayTracking = window.sessionReplay.plugin();
const instance = window.amplitude.createInstance();
instance.add(sessionReplayTracking);
instance.init(API_KEY);
<script>
문제 해결
누락되거나 불완전하거나 사용할 수 없는 리플레이의 경우 세션 리플레이 문제 해결로 이동하십시오. 수집 상태의 경우 세션 리플레이 수집 모니터링을 사용하십시오.
CSS 스타일이 재생에 나타나지 않습니다.
세션 리플레이는 사이트의 CSS 파일과 기타 정적 자산에 대한 참조를 저장하고 해당 참조를 사용하여 재생을 재구성합니다. 파일이 이동하거나 인증이 필요한 경우, Amplitude는 재생 중에 해당 파일을 로드하지 못할 수 있습니다.
- 사이트의 자산이 이동되거나 이름이 변경됩니다. 이 문제는 응용 프로그램의 새 버전을 배포할 때 발생할 수 있습니다.
- 귀하의 사이트에 있는 자산은 Amplitude가 해당 자산을 가져오지 못하도록 하는 액세스 제어 뒤에 있습니다.
CSS 로딩 문제를 해결하는 데 도움이 되는 방법:
도메인에 공개적으로 액세스할 수 있는지 확인하십시오. 로컬 환경에서 작업하는 경우 Amplitude는
localhost에 저장된 자산에 액세스할 수 없을 수도 있습니다.CDN은 오래된 재생에 대한 오래된 스타일시트를 계속 추적해야 합니다. 동일한 스타일시트의 콘텐츠가 시간별로 변경되는 경우 자산 URL에 고유한 문자열이나 해시를 추가해 보십시오. 예를 들어
stylesheet.css?93f8b89.서버의 CORS 구성이 허용하는 도메인 목록에
app.amplitude.com또는app.eu.amplitude.com를 추가합니다.세션 리플레이에 외부 스타일시트에 액세스할 수 있도록 합니다. 세션 리플레이가 외부 스타일시트를 캡처할 수 있도록 하려면 코드의
<link rel="stylesheet">요소에 해당crossorigin="anonymous"속성을 추가하십시오.이는 브라우저가 자격 증명을 보내지 않고 CSS를 로드하도록 지시하며, 이는 스타일시트 규칙에 대한 교차 출처 액세스를 허용합니다. 이 속성이 없으면 Google Chrome과 같은 브라우저는 이러한 규칙에 대한 프로그래밍 방식의 액세스를 차단합니다(예: 읽기 시도가
stylesheet.cssRules실패함).이러한 제한 사항으로 인해 세션 리플레이가 스타일 정보를 캡처하지 못하게 되어 시각적 재생이 불완전하거나 손상됩니다.
캡처 세션에는 제한된 정보만 포함됨
Amplitude는 세션 리플레이가 세션을 캡처할 때 자동으로 [Amplitude] Replay Captured이벤트를 생성합니다. 구현에서 이 이벤트가 표시되지 않는 경우, 리플레이가 퍼널 분석, 세그멘테이션 또는 여정 분석 차트와 같은 Amplitude의 분석 도구에 제대로 표시되지 않을 수 있습니다. 세션 리플레이 홈 페이지 또는 사용자 프로필 페이지에서 세션 리플레이를 계속 확인할 수 있습니다. 이 이벤트를 볼 수 없다면 Amplitude 서포트에 문의하세요.
브라우저 SDK 이외의 다른 방법을 사용하여 이벤트를 계측하는 경우에는 세션 리플레이 독립형 SDK 사용을 고려하십시오.
재생 길이와 세션 길이가 일치하지 않습니다.
일부 시나리오에서는 리플레이 길이가 [Amplitude] Start Session 및 [Amplitude] End Session 이벤트 사이의 시간을 초과할 수 있습니다. 이 문제는 사용자가 브라우저나 브라우저 탭을 닫고 [Amplitude] End Session이(가) 발생하지만, Browser SDK와 세션 리플레이 플러그인이 아직 이를 처리하지 않았을 때 발생합니다. 사용자가 해당 페이지를 다시 방문하면 SDK와 플러그인이 이벤트를 처리하여 리플레이와 함께 Amplitude로 전송합니다. End Session Client Event Time 및 Client Upload Time 간의 불일치가 확인되면 이 시나리오가 발생하는 것임을 알 수 있습니다.
세션 재생은 다음과 같은 이유로 Amplitude에 나타나지 않을 수 있습니다.
- 콘텐츠 보안 정책
- 차단된 JavaScript
- 현재 세션에서 브라우저 SDK를 통해 트리거된 이벤트가 없습니다.
- 샘플링
콘텐츠 보안 정책
사이트에 세션 리플레이 스크립트를 추가할 때, 세션 리플레이 SDK가 실행되는 페이지를 방문하여 브라우저의 개발자 도구를 엽니다.
JavaScript 콘솔에서 Content Security Policy 텍스트를 포함하는 오류 메시지가 있는지 확인하십시오. 예를 들어 Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy.
이 오류를 해결하려면 사이트의 콘텐츠 보안 정책을 업데이트하여 Amplitude의 API에 대한 연결을 허용하십시오.
차단된 JavaScript
브라우저 확장 기능 또는 네트워크 보안 정책이 세션 리플레이 SDK를 차단할 수 있습니다. 브라우저의 개발자 도구를 확인하여 요청이 실패하는지 확인하고, 실패하는 경우 차단된 도메인에 대해 예외를 추가하십시오.
현재 세션에서 브라우저 SDK를 통해 트리거된 이벤트가 없습니다.
세션 리플레이를 사용하려면 사용자 세션 내 최소 하나의 이벤트에 [Amplitude] Session Replay ID 속성이 포함되어 있어야 합니다. Browser SDK Session Start 및 Session End 이벤트에는 기본적으로 이 속성이 포함됩니다. Amplitude Browser SDK 2 이외의 다른 SDK를 사용하여 이벤트를 계측하는 경우, 세션 리플레이 Standalone SDK를 사용하고 필요한 이벤트 속성으로 이벤트에 태그를 지정하십시오.
로컬 테스트의 경우 세션 리플레이가 작동하는지 확인하기 위해 세션 시작 이벤트를 강제로 적용하십시오.
- 브라우저의 개발자 도구를 열고
AMP_로 시작하는 쿠키를 모두 삭제합니다. - 개발자 도구를 닫고 페이지를 새로 고칩니다.
- Amplitude의 사용자 조회 이벤트 스트림은
[Amplitude] Session Replay ID속성을 포함하는 세션 시작 이벤트를 표시합니다. 처리가 완료되면 해당 세션에 대해 세션 재생 버튼이 나타납니다.
샘플링
세션 리플레이의 기본 sampleRate는 0입니다. 속도를 더 높은 숫자로 업데이트하십시오. 자세한 내용은 샘플링 비율로 이동하십시오.
일부 세션에는 세션 리플레이 ID 속성이 포함되지 않습니다.
세션 리플레이는 세션의 모든 이벤트가 [Amplitude] Session Replay ID속성을 가질 필요는 없으며, 세션 내의 한 이벤트만 이 속성을 가지면 됩니다. 세션 리플레이에 연결하는 소스와 다른 소스를 사용하여 이벤트를 계측할 때 속성이 없을 수 있습니다. 예를 들어 애플리케이션이 브라우저 SDK가 아닌 백엔드 소스에서 이벤트를 전송할 수 있습니다.
세션 리플레이 처리 오류
처리 지연, 불일치하는 식별자, 짧은 세션, 불완전한 페이지 계측 및 만료된 리플레이에 대해서는 세션 리플레이 문제 해결로 이동하십시오. 리텐션 규칙을 확인하려면 세션 리플레이 데이터 생애주기 분석 참조로 이동하십시오.
이 내용이 도움이 되었나요?
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.