세션 리플레이 독립형 SDK입니다.
세션 리플레이 계측
세션 리플레이는 기본적으로 활성화되어 있지 않으며, 표준 Amplitude 계측 이상의 설정이 필요합니다.
세션 리플레이 독립형 SDK는 Amplitude Browser SDK와는 별개로 세션 녹화를 사이트에 추가합니다. 제품 내 분석을 위해 Amplitude 이외의 공급자를 사용하는 경우, 이 옵션을 선택하십시오. 사이트에서 이미 Amplitude Browser SDK를 사용하고 있다면 세션 리플레이 Browser SDK 플러그인을 사용하십시오.
세션 리플레이 및 성능
Amplitude는 다음과 같은 방법으로 웹 페이지 성능에 미치는 영향을 최소화하기 위해 세션 리플레이를 구축했습니다.
- 효율적인 압축과 최적화된 번들 크기를 위해 웹후크를 통해 비동기적으로 처리(활성화된 경우).
- 배치 처리 및 경량 압축을 사용하여 네트워크 연결 및 대역폭을 줄입니다.
- DOM 처리 최적화.
번들 크기
세션 리플레이 독립형 SDK는 애플리케이션의 번들 크기를 늘립니다.
현재 번들 크기 정보는 npm 패키지 페이지 또는 BundlePhobia를 확인하세요.
런타임 성능
세션 리플레이는 비동기식으로 실행되며 기본 스레드를 차단하지 않도록 백그라운드에서 재생 데이터를 처리합니다. 성능 특성은 다음과 같습니다.
- DOM 캡처: DOM 스냅샷 캡처는 일반적으로 각 페이지 상호 작용에 대해 5ms 미만의 처리 시간을 추가합니다. 초기 페이지 로드 스냅샷 캡처는 페이지의 복잡도에 따라 10~50ms 정도 걸립니다.
- 메모리 사용량: 세션 리플레이는 재생 이벤트를 메모리 또는 IndexedDB에 저장합니다(
storeType를 사용하여 구성 가능). 메모리 사용량은 세션 길이와 페이지 복잡성에 따라 증가하며, 일반적으로 각 활성 세션에 대해 1~10MB의 범위입니다. - CPU 영향: 기본 설정을 사용하면 세션 리플레이가 정상적인 작동 중에 CPU 시간을 2% 미만으로 사용합니다. Amplitude는
performanceConfig.enabled인 경우 압축 작업을 브라우저의 유휴 기간으로 연기합니다(기본값)true. - 네트워크 대역폭: Amplitude는 업로드 전에 재생 데이터를 압축하므로 일반적으로 페이로드 크기를 60~80% 줄입니다. Amplitude는 네트워크 요청을 일괄 처리하여 비동기적으로 전송합니다.
성능 최적화
세션 리플레이 성능을 최적화하려면 다음을 수행하십시오.
- 메인 스레드에서 압축을 이동할 수 있도록 설정하여 메인 스레드에 대한 CPU 영향을 줄입니다
useWebWorker. - 지연된 압축이 발생할 시기를 제어하도록
performanceConfig.timeout구성합니다. - 캡처되는 세션 수를 줄이는 데 사용하면 CPU 및 메모리 사용량을 직접적으로 줄일 수 있습니다
sampleRate. - 페이지 재로드 시 지속성이 필요하지 않은 경우
storeType으로 설정하여 IndexedDB 오버헤드를 줄입니다memory.
자세한 성능 테스트 결과는 세션 리플레이 성능 테스트 블로그 게시물을 참조하십시오.
세션 리플레이는 섀도우 DOM의 요소를 포함하여 페이지의 문서 객체 모델(DOM)에 대한 변경 사항을 캡처한 다음 이러한 변경 사항을 재생하여 비디오와 유사한 재생을 생성합니다. 세션이 시작될 때 세션 리플레이는 페이지의 DOM에 대한 전체 스냅샷을 캡처합니다. 사용자가 페이지와 상호작용할 때, 세션 리플레이는 DOM에 대한 각 변경 사항을 차이로 캡처합니다. 세션의 재생을 시청할 때, 세션 리플레이는 각 차이를 순차적으로 원본 DOM에 다시 적용하여 재생을 구성합니다. 세션 리플레이에는 최대 길이가 없습니다.
SDK 초기화 지연
페이지가 로드될 때까지 세션 리플레이 초기화를 연기하면 페이지 로드 지표에 대한 SDK의 기여도가 제거됩니다. Time to Interactive 또는 Largest Contentful Paint와 같은 로드 시간 지표를 측정하고 세션 리플레이의 영향을 전혀 받지 않아야 할 때 이 접근 방식을 사용하십시오. 조기 초기화를 유지하면서 영향을 줄이려는 것이 목표인 경우 대신 성능 최적화의 구성 옵션을 사용하십시오.
load이벤트 리스너를 사용하여 초기화를 연기합니다.
import 3rdPartyAnalytics from 'example';
window.addEventListener('load', async () => {
const sessionReplay = await import('@amplitude/session-replay-browser');
await sessionReplay.init(AMPLITUDE_API_KEY, {
deviceId: '<string>',
sessionId: '<string | number>',
sampleRate: 0.5,
}).promise;
});
또는 requestIdleCallback를 사용하여 브라우저가 유휴 상태가 될 때까지 연기합니다. 이 접근 방식은 활동이 적은 순간을 기다리므로 다른 로드 후 작업과의 경합이 줄어듭니다.
import 3rdPartyAnalytics from 'example';
requestIdleCallback(async () => {
const sessionReplay = await import('@amplitude/session-replay-browser');
await sessionReplay.init(AMPLITUDE_API_KEY, {
deviceId: '<string>',
sessionId: '<string | number>',
sampleRate: 0.5,
}).promise;
});
세션 리플레이는 초기화 시 전체 DOM 스냅샷을 캡처합니다. 초기화 전에 발생한 상호작용은 재생에 나타나지 않습니다.
전제 조건
세션 리플레이 독립형 SDK의 요구 사항은 다음과 같습니다.
- 귀하의 애플리케이션은 웹 기반입니다.
- 초기화 시 SDK에 세션 식별자를 제공하고 변경될 때 호출합니다
setSessionId. SDK는 이 ID를 사용하여 재생 데이터를 버킷화합니다. 세션 ID 일치를 위해 분석 이벤트와 SDK에서 동일한 세션 식별자를 사용하십시오. 시간 기반 이벤트 매칭만 사용하는 경우 세션 리플레이는 분석 이벤트에 나타나지 않는 프런트엔드에서 생성된 시간 버킷(예: 밀리초 단위의 시간 정렬된 Unix 타임스탬프)일sessionId수 있습니다. - SDK에 장치 ID를 제공할 수 있습니다.
Device ID독립형 SDK에 전달하는 값은 분석 이벤트의 장치 ID와 일치해야 합니다.
독립형 SDK는 세션 관리 기능을 제공하지 않습니다. 애플리케이션 또는 타사 연동 기능은 Session ID 및 Device ID에 대한 변경 사항을 적용하여 SDK를 업데이트해야 합니다.
빠른 시작
플러그인을 npm 또는 yarn으로 설치하세요.
통합 SDK
브라우저 통합 SDK를 설치하여 실험 SDK와 다른 Amplitude 제품(분석, 세션 리플레이)에 액세스하십시오. 통합 SDK는 모든 Amplitude 기능을 위한 단일 진입점을 제공하며 모든 구성 요소의 초기화 및 구성을 처리합니다.
# Install Session Replay SDK only
npm install @amplitude/session-replay-browser --save
# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified
애플리케이션 코드를 구성합니다.
- 재생 수집을 시작하려면
sessionReplay.init호출하십시오. API 키, 세션 식별자 및 장치 식별자를 전달합니다. - 세션 식별자가 변경되면
sessionReplay.setSessionId을 사용하여 새 값을 Amplitude에 전달하십시오. - Amplitude는 재생을 분석 데이터와 연결하기 위한
[Amplitude] Replay Captured이벤트를 자동으로 생성합니다. 자세한 내용은 세션 리플레이 ID를 참조하십시오.
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'
const AMPLITUDE_API_KEY = "key"
// Configure the SDK and begin collecting replays
await sessionReplay.init(AMPLITUDE_API_KEY, {
deviceId: "<string>",
sessionId: "<string | number>",
optOut: false,
sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
}).promise;
// Call whenever the session id changes
await sessionReplay.setSessionId(sessionId).promise;
세션 리플레이 계측은 Amplitude 프로젝트의 맥락에서 발생합니다. Amplitude는 조직 수준에서 재생 할당량을 정의합니다. 여러 프로젝트에 걸쳐 여러 세션 리플레이 구현을 가질 수 있으며, 각 프로젝트는 고유한 샘플링 속도를 갖고 있으며 동일한 할당량에서 데이터를 수집합니다.
또한 스크립트 태그를 사용하여 세션 리플레이를 계측할 수도 있습니다.
<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.52.0-min.js.gz"></script>
<script>
window.sessionReplay.init(AMPLITUDE_API_KEY, {
deviceId: "<string>",
sessionId: "<string | number>",
sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
//...other options
})
// Call whenever the session id changes
window.sessionReplay.setSessionId(sessionId);
</script>
세션 리플레이 ID
Amplitude는 세션 리플레이가 세션을 캡처할 때 자동으로 [Amplitude] Replay Captured 이벤트를 생성합니다. 이 이벤트에는 재생을 분석 데이터에 연결하는 [Amplitude] Session Replay ID속성이 포함됩니다. 수동 계측이 필요하지 않습니다.
[Amplitude] Session Replay ID 는 재생에 대한 고유 식별자로, 기본적으로 사용자의 세션을 식별하는 [Amplitude] Session ID과는 다릅니다.
세션 리플레이 ID의 형식은 <deviceId>/<sessionId>입니다. 세션 리플레이는 /를 구분 기호로 사용하기 때문에 deviceId와 사용자 지정 세션 ID 문자열 값에는 /를 포함할 수 없습니다. 허용되는 문자: a-z A-Z 0-9 _ - . | @ : =. 추가 캐릭터가 필요하면 Amplitude 지원팀에 문의하십시오.
Amplitude는 세션 리플레이 ID로 리플레이를 연결합니다. 여러 세션을 단일 재생으로 결합하려면 각 세션이 동일한 장치 ID 및 세션 ID를 참조하는지 확인하십시오.
기존 구현
: 를 사용하여 이벤트에 수동으로 [Amplitude] Session Replay ID속성을 추가하는 기존 구현이 있는 getSessionReplayProperties()경우, 이 방법은 계속 작동합니다. 그러나 Amplitude는 자동 [Amplitude] Replay Captured 이벤트를 권장합니다.
재생이 보이지 않나요?
Amplitude UI에 재생이 나타나지 않는 경우, 해당 [Amplitude] Replay Captured 이벤트가 프로젝트에 나타나는지 확인하세요. 이 이벤트를 볼 수 없다면 Amplitude 서포트에 문의하세요.
구성
세션 리플레이 SDK를 초기화할 때 다음 구성 옵션을 전달하십시오.
| 이름 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
deviceId | string | 예 | undefined | 애플리케이션을 실행하는 장치의 식별자를 설정합니다. |
sessionId | string | number | 예 | undefined | 사용자의 현재 세션에 대한 식별자를 설정합니다. 표준 세션 추적을 위해 밀리초 number단위의 Unix 타임스탬프를 사용하거나 사용자 정의 세션 정의를 위해 사용자 정의 문자열을 사용하십시오. 사용자 정의 문자열 값은 허용된 문자 집합을 따라야 합니다. |
sampleRate | number | 아니요 | 0 | Amplitude가 재생 수집을 위해 선택하는 세션 수를 제어합니다. 숫자는 0과 1 사이의 소수입니다. 예를 들어 0.4는 Amplitude가 재생 수집을 위해 무작위로 선택한 세션의 비율을 나타냅니다. 많은 수의 세션 중에서 0.4는 해당 세션의 40%을 선택합니다. 소수점 이하 6자리(0.000001)만큼 작은 샘플링 속도가 작동합니다. |
optOut | boolean | 아니요 | false | 세션에 대한 재생을 수집할 수 있는 권한을 설정합니다. 값이 true이면 Amplitude가 세션 재생을 수집하지 못하게 됩니다. |
flushMaxRetries | number | 아니요 | 5 | 실패한 업로드 시도에 대한 최대 재시도 횟수를 설정합니다. 이는 Amplitude가 재시도할 수 있는 오류에만 적용됩니다. |
logLevel | number | 아니요 | LogLevel.Warn | LogLevel.None 또는 LogLevel.Error또는 LogLevel.Warn또는 LogLevel.Verbose또는 LogLevel.Debug. 로그 수준을 설정합니다. |
loggerProvider | Logger | 아니요 | Logger | 로그 메시지를 목적지로 전송하도록 로거에서 사용자 지정 loggerProvider 클래스를 설정합니다. |
serverZone | string | 아니요 | US | EU 또는 US. Amplitude 서버 영역을 설정합니다. EU 데이터 센터에서 생성된 Amplitude 프로젝트의 경우 이 값을 EU로 설정하십시오. |
privacyConfig | object | 아니요 | undefined | CSS 선택기를 사용하여 고급옵션 마스킹 구성을 지원합니다. 자세한 내용은 화면 상의 데이터 마스킹을 참조하십시오. |
applyBackgroundColorToBlockedElements | boolean | 아니요 | false | true인 경우 시각적 마스킹을 위해 차단된 요소에 배경색을 적용합니다. 이를 통해 Amplitude가 재생에서 캡처를 차단하는 요소를 시각화할 수 있습니다. |
debugMode | boolean | 아니요 | false | API 키의 해시가 포함된 [Amplitude] Session Replay Debug이벤트 속성을 추가하여 앱 불일치와 같은 계측 문제를 디버깅하는 데 도움이 됩니다. Amplitude는 초기 설정을 디버깅할 때만 이 방법을 권장하며, 프로덕션용으로는 사용하지 않습니다. |
configServerUrl | string | 아니요 | undefined | 원격 구성을 가져올 엔드포인트 URL을 지정합니다. 제공된 경우, 기본 서버 영역 구성을 재정의합니다. |
trackServerUrl | string | 아니요 | undefined | 세션 리플레이 데이터를 전송할 엔드포인트 URL을 지정합니다. 제공된 경우 SDK는 요청을 기본 SR 엔드포인트 대신 해당 엔드포인트로 전달합니다. |
shouldInlineStylesheet | boolean | 아니요 | true | Amplitude가 스타일시트를 인라인화하는 경우 스타일시트의 내용을 저장합니다. 다음 기간동안 리플레이 시 Amplitude는 원격으로 가져오는 대신 저장된 스타일시트를 사용합니다. 이렇게 하면 스타일시트가 누락되어 재생이 끊어진 것으로 나타나는 것을 방지할 수 있습니다. 인라이닝 스타일시트는 모든 경우에 작동하지 않을 수 있습니다. 이 값이 정의되지 않은 경우 Amplitude는 스타일시트를 인라인화합니다. |
storeType | string | 아니요 | idb | Amplitude가 재생 이벤트를 저장하는 방법을 지정합니다. idb는 SDK가 캡처 다음 기간동안 모든 이벤트를 전송할 수 없는 경우 IndexedDB를 사용하여 재생 이벤트를 유지합니다. memory는 재생 이벤트를 메모리에만 저장하므로 페이지가 닫힐 때 이벤트가 손실됩니다. IndexedDB를 사용할 수 없는 경우 시스템은 메모리로 폴백합니다. |
performanceConfig.enabled | boolean | 아니요 | true | 활성화된 경우 Amplitude는 브라우저의 유휴 기간 다음 기간동안 이벤트 압축이 발생하도록 지연합니다. |
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는 사용자 입력, 텍스트 및 기타 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 인터페이스에서 정의한 개인정보 보호 설정 없이 캡처가 방지됩니다.
사용자 옵트아웃
세션 리플레이는 옵트아웃 구성 옵션을 제공합니다. 초기화의 일부로 전달될 경우 이는 Amplitude가 세션 리플레이를 수집하지 못하도록 방지합니다. 예를 들면 다음과 같습니다.
// Pass a boolean value to indicate a users opt-out status
await sessionReplay.init(AMPLITUDE_API_KEY, {
optOut: true,
}).promise;
콘텐츠 보안 정책(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",
}).promise;
샘플링 속도
기본적으로 세션 리플레이는 재생을 위해 세션의 0%를 캡처합니다. sampleRate구성 옵션을 사용하여 세션 리플레이가 캡처하는 총 세션의 비율을 설정합니다. 예를 들면 다음과 같습니다.
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
sampleRate: 0.01,
}).promise;
수동 및 동적 샘플링, 할당량 계획 및 remote-setting 우선 순위를 확인하려면 세션 리플레이 샘플링 구성으로 이동하십시오.
리플레이 수집 비활성화
세션 리플레이를 활성화한 후에는 다음 중 하나가 발생할 때까지 사이트에서 실행됩니다.
- 사용자가 귀하의 사이트를 떠납니다.
sessionReplay.shutdown()을(를) 호출하십시오.
사용자가 사이트의 제한된 영역으로 이동하기 전에 sessionReplay.shutdown()를 호출하여 사용자가 해당 영역에 있는 동안 리플레이 수집을 비활성화하십시오.
사용자가 사이트의 제한되지 않은 영역으로 돌아왔을 때 재생 수집을 다시 활성화하려면 sessionReplay.init(API_KEY, {...options})호출하십시오.
또한 Amplitude 실험과 같은 기능 플래그 제품을 사용하여 위치와 같은 기준에 따라 리플레이 수집을 활성화하거나 비활성화하는 로직을 만들 수도 있습니다. 예를 들어, 특정 사용자 그룹을 대상으로 하는 기능 플래그를 생성하고 이를 초기화 논리에 추가할 수 있습니다.
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'
const AMPLITUDE_API_KEY = <...>
await sessionReplay.init(AMPLITUDE_API_KEY, {
deviceId: <string>,
sessionId: <string | number>,
optOut: <boolean>,
sampleRate: <number>
}).promise;
데이터 리텐션
세션 리플레이는 개인정보 보호 및 삭제 요청에 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를 권장합니다.
알려진 제한 사항
세션 리플레이를 구현할 때 다음과 같은 제한 사항에 유의하십시오.
- 세션 리플레이는 여러 프로젝트에 걸쳐 단일 사용자의 재생을 함께 연결하지 않습니다. 예를 들면 다음과 같습니다.
- 마케팅 사이트와 웹 애플리케이션을 각각 세션 리플레이가 활성화된 별도의 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 또는 이미지와 같이 인증이 필요한 자산입니다.
- 세션 리플레이는 광고 차단 소프트웨어와 호환되지 않습니다.
문제 해결
누락되거나 불완전하거나 사용할 수 없는 리플레이의 경우 세션 리플레이 문제 해결으로 이동하십시오. 수집 상태의 경우 세션 리플레이 수집 모니터링을 사용하십시오.
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] 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를 차단할 수 있습니다. 브라우저의 개발자 도구를 확인하여 요청이 실패하는지 확인하고, 실패하는 경우 차단된 도메인에 대해 예외를 추가하십시오.
샘플링
세션 리플레이의 기본 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.