이 페이지에서

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.

세션 리플레이 브라우저 SDK 플러그인

npmv1.35.539.1 kB gzip

세션 리플레이 계측

세션 리플레이는 기본적으로 켜져 있지 않으며 표준 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에 다시 적용하여 재생을 구성합니다. 세션 리플레이에는 최대 길이가 없습니다.

시작하기 전에

세션 리플레이 플러그인을 사용하려면 다음이 필요합니다.

  1. 귀하의 애플리케이션은 웹 기반입니다.
  2. SDK에 장치 ID를 제공할 수 있습니다.
  3. 귀하의 사이트는 브라우저 2.0 SDK를 사용합니다.

지원되는 브라우저

세션 리플레이는 Amplitude의 SDK와 동일한 브라우저 세트를 지원합니다. 자세한 내용은 브라우저 호환성을 참조하십시오.

세션 리플레이는 브라우저 확장 기능 중 일부나 브라우저 확장 기능이 도입한 DOM 요소를 지원하지 않을 수도 있습니다.

세션 리플레이는 섀도우 DOM을 지원하지만 사이트에서 사용하는 프레임워크에 따라 예외가 있을 수 있습니다.

빠른 시작

플러그인을 npm 또는 yarn으로 설치하세요.

통합 SDK

브라우저 SDK를 아직 설치하지 않은 경우, 브라우저 통합 SDK를 대신 사용하는 것을 고려해 보십시오. 통합 SDK는 모든 Amplitude 기능(분석, 세션 리플레이, 실험)에 대한 단일 진입점을 제공하며, 모든 구성 요소의 초기화 및 구성을 처리함으로써 연동을 단순화합니다.

# If you already have Browser SDK installed, install the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save
# OR if you haven't installed Browser SDK yet, use the Unified SDK instead
npm install @amplitude/unified

애플리케이션 코드를 구성합니다.

import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
// Create and Install Session Replay Plugin
const sessionReplayTracking = sessionReplayPlugin();
amplitude.add(sessionReplayTracking);
// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);

또한 해당 코드를 사이트의 <head>에 직접 추가할 수도 있습니다. 이 방법을 사용하면 애플리케이션이 다른 곳에서 브라우저 SDK를 초기화하지 않도록 해야 합니다. 브라우저 SDK를 두 번 이상 초기화하면 장치 ID 또는 세션 ID가 일치하지 않을 수 있습니다.

html
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.47.2-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.35.5-min.js.gz"></script>
<script>
  const sessionReplayTracking = window.sessionReplay.plugin();
  window.amplitude.add(sessionReplayTracking);
  window.amplitude.init(API_KEY);
</script>

세션 리플레이 계측은 Amplitude 프로젝트의 맥락에서 발생합니다. Amplitude는 조직 수준에서 리플레이 할당량을 정의합니다. 따라서 여러 프로젝트에 걸쳐 여러 세션 리플레이 구현을 가질 수 있으며, 각 프로젝트는 고유한 샘플링 속도를 갖고 동일한 할당량에서 데이터를 수집할 수 있습니다.

Google

태그 관리자와의 호환성: 세션 리플레이 플러그인 스크립트는 페이지의 <head>태그에 추가할 때 비동기적으로 로드됩니다. 결과적으로 이 구현은 Google 태그 관리자와 호환되지 않습니다. 자세한 내용은 Google 태그 관리자를 사용한 세션 리플레이 구현을 참조하세요.

구성

이름유형필수기본값설명
sampleRatenumber아니요0리플레이 수집을 위해 선택할 세션 수를 제어합니다. 숫자는 0과 1 사이의 소수입니다. 예를 들어 0.4는 Amplitude가 재생 수집을 위해 무작위로 선택한 세션의 비율을 나타냅니다. 많은 수의 세션 중에서 0.4는 해당 세션의 40%을 선택합니다. 세션 리플레이는 샘플링 속도를 포함한 설정의 원격 구성을 지원하기 때문에 이 필드는 필수가 아닙니다.
privacyConfigobject아니요undefinedCSS 선택기를 사용하여 고급옵션 마스킹 구성을 지원합니다.
applyBackgroundColorToBlockedElementsboolean아니요falsetrue인 경우 시각적 마스킹을 위해 차단된 요소에 배경색을 적용합니다. 이를 통해 세션 리플레이가 캡처를 차단하는 요소를 확인할 수 있습니다.
debugModeboolean아니요false앱 불일치 등의 계측 문제를 디버깅하는 데 도움이 되는 디버그 이벤트 속성을 추가합니다. 초기 설정을 디버깅할 때만 권장되며 프로덕션에는 권장되지 않습니다.
serverZonestring아니요USEU 또는 US. Amplitude 서버 영역을 설정합니다. EU 데이터 센터의 Amplitude 프로젝트에 대해서는 이 값을 EU로 설정하십시오.
configServerUrlstring아니요undefined원격 구성을 가져올 엔드포인트 URL입니다. 제공된 경우, 기본 서버 영역 구성을 재정의합니다.
trackServerUrlstring아니요undefined세션 리플레이 데이터를 전송하기 위한 엔드포인트 URL입니다. 제공된 경우, Amplitude는 기본 세션 리플레이 엔드포인트 대신 SDK의 요청을 해당 위치로 전달합니다.
shouldInlineStylesheetboolean아니요truetrue인 경우 세션 리플레이는 인라인 스타일시트의 내용을 저장합니다. 재생 중에 세션 리플레이는 원격으로 가져오는 대신 저장된 스타일시트를 사용합니다. 이렇게 하면 스타일시트가 누락되어 재생이 끊어진 것으로 나타나는 것을 방지할 수 있습니다. 인라이닝 스타일시트는 모든 경우에 작동하지 않을 수 있습니다. 정의되지 않은 경우 세션 리플레이는 스타일시트를 인라이닝합니다.
storeTypestring아니요idb세션 리플레이가 재생 이벤트를 저장하는 방법. idb세션 리플레이가 캡처 중에 모든 이벤트를 전송할 수 없는 경우 IndexedDB를 사용하여 재생 이벤트를 유지합니다. memory재생 이벤트를 메모리에만 저장하므로 페이지가 닫힐 때 이벤트가 손실됩니다. IndexedDB를 사용할 수 없는 경우 시스템은 메모리로 폴백합니다.
performanceConfig.enabledboolean아니요true활성화된 경우 세션 리플레이는 브라우저의 유휴 다음 기간동안 이벤트 압축이 발생하도록 지연합니다.
performanceConfig.timeoutnumber아니요undefinedrequestIdleCallback API에 대한 선택적 시간 초과(밀리초)입니다. 이 값을 지정하면 브라우저가 유휴 상태가 아니더라도 지연된 압축 작업을 실행하기 전에 브라우저가 대기할 최대 시간을 설정합니다.
useWebWorkerboolean아니요false웹 워커를 사용하여 재생 이벤트를 압축합니다. 이렇게 하면 메인 스레드에서 압축을 제거하여 성능이 향상됩니다.

API 엔드포인트

세션 리플레이는 다음 API 엔드포인트를 사용합니다.

  • 데이터 수집:
    • 미국: 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 구성 옵션을 사용하여 이러한 기본값을 재정의할 수 있습니다.

기본 세션 이벤트 추적

세션 리플레이는 기본적으로 세션 추적을 활성화합니다. 이를 통해 세션 리플레이는 세션 시작 및 세션 종료 이벤트를 캡처합니다. 세션 리플레이를 구현하기 전에 이러한 이벤트를 캡처하지 않았다면 이벤트 볼륨이 증가할 것으로 예상됩니다. 세션 추적에 대한 자세한 내용은 브라우저 SDK 2.0 | 세션 추적을 참조하십시오.

브라우저 SDK 구성을 사용하여 암시적으로 세션 추적을 활성화하십시오.

js
amplitude.init(API_KEY, USER, {
  autocapture: {
    sessions: true,
  },
});

세션 시작 및 세션 종료 이벤트

플러그인 버전 1.12.1부터 세션 리플레이는 더 이상 기본적으로 Session End이벤트를 캡처하지 않습니다Session Start. 이러한 이벤트를 캡처할 수 있도록 설정하려면 forceSessionTracking: true:

js
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는 리플레이 재생을 활성화하기 위해 캡처된 전체 세션에 최소 하나의 이벤트가 필요합니다.

화면상의 데이터 마스킹

The Session Replay SDK offers three ways to mask user input, text, and other HTML elements.

ElementDescription
<input>Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To unmask a text input, add the class .amp-unmask. For example: <input class="amp-unmask">.
textTo mask text within non-input elements, add the class .amp-mask. For example, <p class="amp-mask">Text</p>. When masked, Session Replay captures masked text as a series of asterisks.
non-text elementsTo block a non-text element, add the class .amp-block. For example, <div class="amp-block"></div>. Session Replay replaces blocked elements with a placeholder of the same dimensions.

Session Replay supports setting a masking level on the Session Replay Settings screen in Amplitude. This includes Light, Medium, and Conservative settings.

Session Replay settings also enable remote masking overrides. These enable users in your organization to configure or update masking after implementation.

In the event of a conflict, Session Replay defers to the remote setting. For example:

.selector-1.selector-2.selector-3
Local settingmask--mask
Remote settingunmaskunmask--
Resultunmaskunmaskmask

In this example, .selector-1 has a local setting and a remote setting. The result follows the remote setting, and overrides the setting in the SDK or plugin implementation.

Specify elements to block or mask in the privacyConfig object during configuration.

js
// 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 selectors

Session Replay's configuration supports many types of CSS Selector. Specify an element tag (h1 or textarea), a class name (.hidden) or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use data attributes, add a custom attribute like data-amp-unmask or data-amp-mask to any HTML element. For example, <textarea data-amp-unmask></textarea>, then enclose the attribute in square brackets when you specify the selector, [data-amp-unmask].

Remote configuration

If remote configuration is enabled, and fails to load, Session Replay doesn't capture any sessions. This ensures that Amplitude respects any privacy settings you define in the Admin interface, and you don't accidentally capture sensitive data.

사용자 옵트아웃

세션 리플레이 플러그인은 브라우저 SDK의 optOut설정을 따르며 사용자 옵트아웃을 자체적으로 지원하지 않습니다.

콘텐츠 보안 정책(CSP)

웹 애플리케이션이 엄격한 콘텐츠 보안 정책을 사용하는 경우 다음 지시어를 추가하십시오.

필수 CSP 지시어

text
script-src: https://cdn.amplitude.com;
connect-src: https://api-secure.amplitude.com;
worker-src: blob:;

CSP 지시어 참조

지시어도메인필수설명
script-srchttps://cdn.amplitude.com예. CDN을 사용하는 경우세션 리플레이 플러그인과 브라우저 SDK를 Amplitude의 CDN에서 로드할 수 있도록 허용합니다.
connect-srchttps://api-secure.amplitude.com예(미국)SDK가 세션 리플레이 데이터를 Amplitude의 미국 서버로 전송할 수 있도록 허용합니다.
connect-srchttps://api.eu.amplitude.com예 (EU)SDK가 재생 데이터를 Amplitude의 EU 서버로 전송할 수 있도록 허용합니다. serverZone: "EU"를 설정한 경우 필수입니다.
worker-srcblob:예. 웹 작업자를 사용하는 경우재생 이벤트 압축 옵션을 활성화한 경우 필수입니다useWebWorker.

API 엔드포인트

세션 리플레이는 다음 엔드포인트로 데이터를 전송합니다.

지역엔드포인트:목적
미국(기본값)https://api-secure.amplitude.com/sessions/track리플레이 데이터 수집.
EUhttps://api.eu.amplitude.com/sessions/trackEU 데이터 상주를 위한 재생 데이터 수집.
미국(기본값)https://api-secure.amplitude.com/sessions/config원격 구성(샘플링 속도 설정).
EUhttps://api.eu.amplitude.com/sessions/configEU 데이터 상주를 위한 원격 구성

CSP 헤더 예제

미국 지역의 경우:

text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;

EU 데이터 센터의 경우:

text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;

trackServerUrl구성 옵션을 configServerUrl사용하여 사용자 지정 엔드포인트를 지정하는 경우 해당 도메인을 대신 connect-src지시어에 추가하십시오.

EU 데이터 상주

세션 리플레이는 EU 데이터 센터를 사용하는 Amplitude 고객에게 제공됩니다. 초기화 중에 serverZone 구성 옵션을 EU(으)로 설정하십시오. 예를 들면 다음과 같습니다.

js
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
  serverZone: "EU", // [tl! ~~]
}).promise;

샘플링 속도

기본적으로 세션 리플레이는 재생을 위해 세션의 0%를 캡처합니다. Amplitude의 새로운 계정 스니펫을 사용하여 계측한 경우, 샘플링 비율은 테스트를 더 쉽게 하기 위해 기본값으로 1(세션의 100%)으로 설정됩니다. [세션 리플레이] 설정 페이지에서 샘플링 속도를 업데이트하거나 sampleRate구성 옵션을 사용하여 세션 리플레이가 캡처하는 총 세션의 비율을 설정하십시오. 예를 들면 다음과 같습니다.

js
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01,
}).promise;

sampleRate를 설정하려면 세션 리플레이 플랜의 월별 할당량을 고려하십시오. 예를 들어 월별 할당량이 2,500,000 세션이고 월별 평균 세션 수가 3,000,000 세션인 경우 할당량은 평균 세션의 83%입니다. 이 경우 샘플링을 한 달 내내 지속하려면 .83을 또는 그 이하로 설정하십시오sampleRate.

샘플링 속도를 고려할 때 다음 사항에 유의하십시오.

  • 월간 세션 할당량에 도달하면 Amplitude는 재생을 위해 세션 캡처를 중단합니다.
  • 세션 할당량은 매월 1일에 재설정됩니다.
  • 월 초에 전체 할당량을 사용하지 않고 샘플링 속도를 사용하여 한 달 동안 세션 할당량을 분배하십시오.
  • 최적의 샘플링 레이트를 찾으려면 Amplitude는 예를 들어 .01과 같이 낮은 수치로 시작할 것을 권장합니다. 이 값이 충분한 리플레이를 캡처하지 못할 경우 며칠 동안 비율을 높이십시오. 캡처된 세션 리플레이 수를 모니터링하는 방법은 캡처된 세션 수 보기를 참조하십시오.

세션 리플레이는 원격 샘플링 속도 설정을 지원합니다. 이를 통해 조직의 사용자가 코드를 변경하지 않고도 구현 후 프로젝트의 샘플링 속도를 구성하거나 업데이트할 수 있습니다. 충돌이 발생할 경우 세션 리플레이는 기본적으로 원격 설정으로 설정됩니다. 자세한 내용은 계정 설정을 참조하십시오.

리플레이 수집 비활성화

세션 리플레이를 활성화한 후에는 다음 중 하나가 발생할 때까지 사이트에서 실행됩니다.

  • 사용자가 귀하의 사이트를 떠납니다.
  • 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속성을 사용하십시오.

js
await amplitude.add(sessionReplayTracking).promise;
await amplitude.remove(sessionReplayTracking.name).promise;
js
const addPromise = amplitude.add(sessionReplayTracking).promise;
addPromise.then(() => {
  amplitude.remove(sessionReplayTracking.name).promise;
});

또한 Amplitude 실험과 같은 기능 플래그 제품을 사용하여 위치와 같은 기준에 따라 리플레이 수집을 활성화하거나 비활성화하는 로직을 만들 수도 있습니다. 예를 들어, 특정 사용자 그룹을 대상으로 하는 기능 플래그를 생성하고 이를 초기화 논리에 추가합니다.

js
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);
}

Data retention

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests.

Consent management and Session Replay

While privacy laws and regulations vary across states and countries, certain constants exist, including the requirements to disclose in a privacy notice the categories of personal information you are collecting, the purposes for its use, and the categories of third parties with which personal information is shared. When implementing a session replay tool, you should review your privacy notice to make sure your disclosures remain accurate and complete. And as a best practice, review your notice with legal counsel to make sure it complies with the constantly evolving privacy laws and requirements applicable to your business and personal information data practices.

Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from the date of ingestion.

Purchase extra retention time, up to a maximum of 12 months. For more information, contact Amplitude Support.

If you purchase extra session volume, Amplitude retains raw replay data for up to 12 months from the date of ingestion. If you need a more strict policy, contact Amplitude support to set the value to 30 days.

Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.

Replays that are outside of the retention period aren't viewable in Amplitude.

DSAR API

Amplitude DSAR API는 세션 재생에 대한 메타데이터를 반환하지만 원시 재생 데이터는 반환하지 않습니다.

Amplitude는 세션 리플레이가 재생을 캡처할 때 [Amplitude] Replay Captured 이벤트를 자동으로 생성합니다. 이 이벤트에는 [Amplitude] 세션 리플레이 ID 속성이 포함되어 있으며, 이 속성은 사용자를 위해 수집된 재생에 대한 정보를 제공합니다.

세션 리플레이 ID의 형식은 <deviceId>/<sessionId>입니다. 사용자 정의 세션 정의를 사용하는 경우 사용자 정의 세션 ID 값은 /를 포함할 수 없으며 허용된 문자(a-z A-Z 0-9 _ - . | @ : =)를 사용해야 합니다. 추가 캐릭터가 필요하면 Amplitude 지원팀에 문의하십시오.

json
{
 "amplitude_id": 123456789,
 "app": 12345,
 "event_time": "2020-02-15 01:00:00.123456",
 "event_type": "first_event",
 "server_upload_time": "2020-02-18 01:00:00.234567",
 "device_id": "your device id",
 "user_properties": { ... },
 "event_properties": {
 "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
 },
 "session_id": 1699922971244,
}

데이터 삭제

세션 리플레이는 Amplitude의 사용자 개인정보 보호 API를 사용하여 삭제 요청을 처리합니다. 삭제 요청이 성공하면 지정된 사용자에 대한 모든 세션 리플레이가 제거됩니다.

세션 리플레이를 사용하는 Amplitude 프로젝트를 삭제하면 Amplitude는 해당 리플레이 데이터를 삭제합니다.

봇 필터

세션 리플레이는 Amplitude 앱이 제공하는 것과 동일한 블록 필터를 사용합니다. 세션 리플레이는 이벤트나 사용자 속성을 기반으로 트래픽을 차단하지 않습니다.

Session Replay storage

Session Replay doesn't set cookies on the user's browser. Instead, it relies on a browser storage option called IndexedDB by default. This option enables continuous replay collection during a session in which the user navigates browser tabs or closes and reopens a tab. The SDK cleans up the data it stores in IndexedDB and shouldn't impact the user's disk space.

If the environment doesn't support IndexedDB, Session Replay falls back to an in-memory storage option. In-memory storage is less durable and data is lost when the user closes their browser window. Set the config option storeType to 'memory' to force in-memory storage.

If a user opts out of all cookies on your site, use the optOut configuration option to disable replay collection for that user.

IndexedDB best practices

To ensure that IndexedDB is initialized and working properly:

  • Review CSP headers to ensure they're not overly restrictive. Ensure default-src and script-src directives allow necessary sources.

  • Perform IndexedDB operations within the same origin. Cross-origin restrictions can block IndexedDB operations.

  • Confirm that users use a modern browser that supports IndexedDB. Amplitude recommends the latest versions of Chrome, Firefox, Safari, Edge, or Opera.

쿠키

세션 리플레이는 쿠키를 직접 사용하지 않으며 쿠키 크기에 영향을 미치지 않습니다. 브라우저 SDK는 세션 관리를 위해 쿠키를 사용합니다.

알려진 제한 사항

세션 리플레이를 구현할 때 다음과 같은 제한 사항에 유의하십시오.

  • 세션 리플레이는 여러 프로젝트에 걸쳐 단일 사용자의 재생을 함께 연결하지 않습니다. 예를 들면 다음과 같습니다.
    • 마케팅 사이트와 웹 애플리케이션을 각각 세션 리플레이가 활성화된 별도의 Amplitude 프로젝트로 계측합니다.
    • 알려진 사용자가 마케팅 사이트에서 시작하여 웹 애플리케이션에 로그인합니다.
    • Amplitude는 두 세션을 모두 캡처합니다.
    • 각 세션의 재생은 호스트 프로젝트에서 볼 수 있습니다.
  • 세션 리플레이는 다음 HTML 요소를 캡처할 수 없습니다.
    • 캔버스
    • WebGL.
    • objectFlash, Silverlight 또는 Java와 같은 플러그인을 포함하는 태그. 세션 리플레이는 object type="image"을 지원합니다.
    • Lottie 애니메이션.
    • crossorigin <iframe>속성으로 세션 리플레이 SDK를 로드하지 않는 교차 출처 <iframe> 요소crossOriginIframes.enabled: true(예: Stripe 또는 Google Maps와 같은 타사 임베드). 퍼스트파티 교차 출처 iframe을 캡처하려면 교차 출처 iframe 녹화로 이동하세요.
    • 글꼴, CSS 또는 이미지와 같이 인증이 필요한 자산입니다.
  • 세션 리플레이는 광고 차단 소프트웨어와 호환되지 않습니다.

여러 Amplitude 인스턴스

세션 리플레이는 Amplitude SDK의 단일 인스턴스에 연결할 수 있도록 지원합니다. 응용 프로그램에서 두 개 이상의 인스턴스를 사용하는 경우 프로젝트와 가장 관련성이 높은 인스턴스에서 세션 리플레이를 시작해야 합니다.

html
<script>
 const sessionReplayTracking = window.sessionReplay.plugin();
  const instance = window.amplitude.createInstance();
  instance.add(sessionReplayTracking);
  instance.init(API_KEY);
<script>

문제 해결

개별 상태 및 오류에 대한 자세한 내용은 세션 리플레이 수집 모니터링으로 이동하십시오.

CSS 스타일이 재생에 나타나지 않습니다.

Amplitude는 재생을 캡처할 때 CSS 파일이나 애플리케이션이나 사이트의 일부인 기타 정적 자산을 다운로드하여 저장하지 않습니다. 해당 자산을 직접 관리하지 않습니다. 세션 리플레이는 이러한 파일에 대한 참조를 저장하고 재생을 재구성할 때 해당 참조를 사용합니다. 경우에 따라 다음과 같은 이유로 재생의 스타일이 사용자의 응용 프로그램과 다를 수 있습니다.

  • 사이트의 자산이 이동되거나 이름이 변경됩니다. 이 문제는 응용 프로그램의 새 버전을 배포할 때 발생할 수 있습니다.
  • 귀하의 사이트에 있는 자산은 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 사용을 고려하십시오.

Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the [Amplitude] Start Session and [Amplitude] End Session events. This happens when a user closes their browser or browser tab and [Amplitude] End Session occurs, but the Browser SDK and Session Replay plugin haven't yet processed it. When the user visits that page again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the End Session Client Event Time and the Client Upload Time.

Session replays may not appear in Amplitude due to:

  • Content security policy
  • Blocked JavaScript
  • No events triggered through the browser SDK in the current session
  • Sampling

Local development and focus state

The Session Replay SDK and plugin capture only the page that's in focus. When you develop locally with the browser console open, focus states may not work as expected. If you don't see replays in Amplitude, try to enable debugMode. In this mode, Session Replay ignores the focus handle and enables extra debugging information.

js
const sessionReplayTracking = window.sessionReplay.plugin({
 debugMode: true,  
 sampleRate: 1, 
 });

Content security policy

When you add the Session Replay script to your site, visit a page on which the Session Replay SDK is running, and open your browser's developer tools.

Check for any error messages in the JavaScript console that contain the text Content Security Policy. For example, Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy.

To resolve this error, update your site's content security policy to allow connection to Amplitude's APIs.

Blocked JavaScript

Browser extensions or network security policy may block the Session Replay SDK. Check your browser's developer tools to see if requests fail, and if so, add an exception for the blocked domains.

No events triggered through the browser SDK in the current session

Session Replay requires that at least one event in the user's session has the [Amplitude] Session Replay ID property. The Browser SDK Session Start and Session End events include this property by default. If you instrument your events with any SDK other than the Amplitude Browser SDK 2, use the Session Replay Standalone SDK and ensure you tag your events with the necessary event properties.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

  1. Open your browser's developer tools, and delete any cookie that begins with AMP_.
  2. Close developer tools and refresh the page.
  3. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the [Amplitude] Session Replay ID property. After processing, the Play Session button should appear for that session.

Sampling

As mentioned above, the default sampleRate for Session Replay is 0. Update the rate to a higher number. For more information see, Sampling rate.

Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the [Amplitude] Session Replay ID property, only that one event in the session has it. Reasons why [Amplitude] Session Replay ID may not be present in an event include:

If you instrument an event with a source different from the source you connect to Session Replay. For example, your application may send events from a backend source, rather than the Browser SDK.

세션 리플레이 처리 오류

일반적으로 재생은 수집 후 몇 분 첫 사용 후 사용할 수 있어야 합니다. 지연 또는 오류는 다음 중 하나 이상으로 인해 발생할 수 있습니다.

  • API 키 또는 장치 ID가 일치하지 않습니다. 이 문제는 세션 리플레이와 표준 이벤트 계측이 서로 다른 API 키 또는 장치 ID를 사용하는 경우 발생할 수 있습니다.
  • 세션 리플레이가 잘못된 프로젝트를 참조합니다.
  • 짧은 세션. 사용자가 초기화 후 몇 초 이내에 이탈하는 경우 SDK가 리플레이 데이터를 업로드할 시간이 없을 수 있습니다.
  • 페이지 계측. 사용자가 방문하는 모든 페이지에서 세션 리플레이가 실행되지 않는 경우 해당 세션이 제대로 캡처되지 않을 수 있습니다.
  • 설정된 리텐션 기간(기본값 30일, 추가 볼륨 구매 시 90일)보다 오래된 리플레이.

이 내용이 도움이 되었나요?