세션 리플레이 독립형 SDK입니다.

세션 리플레이 독립형 SDK는 Amplitude Browser SDK와는 별개로 세션 녹화를 사이트에 추가합니다. 제품 내 분석을 위해 Amplitude 이외의 공급자를 사용하는 경우, 이 옵션을 선택하십시오. 사이트에서 이미 Amplitude Browser SDK를 사용하고 있다면 세션 리플레이 Browser SDK 플러그인을 사용하십시오.

번들 크기

세션 리플레이 독립형 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의 요구 사항은 다음과 같습니다.

1. 귀하의 애플리케이션은 웹 기반입니다.
2. 초기화 시 SDK에 세션 식별자를 제공하고 변경될 때 호출합니다setSessionId. SDK는 이 ID를 사용하여 재생 데이터를 버킷화합니다. 세션 ID 일치를 위해 분석 이벤트와 SDK에서 동일한 세션 식별자를 사용하십시오. 시간 기반 이벤트 매칭만 사용하는 경우 세션 리플레이는 분석 이벤트에 나타나지 않는 프런트엔드에서 생성된 시간 버킷(예: 밀리초 단위의 시간 정렬된 Unix 타임스탬프)일 sessionId수 있습니다.
3. SDK에 장치 ID를 제공할 수 있습니다.
4. Device ID독립형 SDK에 전달하는 값은 분석 이벤트의 장치 ID와 일치해야 합니다.

독립형 SDK는 세션 관리 기능을 제공하지 않습니다. 애플리케이션 또는 타사 연동 기능은 Session ID 및 Device ID에 대한 변경 사항을 적용하여 SDK를 업데이트해야 합니다.

빠른 시작

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

# 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

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

1. 재생 수집을 시작하려면 sessionReplay.init호출하십시오. API 키, 세션 식별자 및 장치 식별자를 전달합니다.
2. 세션 식별자가 변경되면 sessionReplay.setSessionId을 사용하여 새 값을 Amplitude에 전달하십시오.
3. 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: "<boolean>",
 sampleRate: "<number>"
}).promise;
// Call whenever the session id changes
await sessionReplay.setSessionId(sessionId).promise;

또한 스크립트 태그를 사용하여 세션 리플레이를 계측할 수도 있습니다.

<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.51.0-min.js.gz"></script>
<script>
window.sessionReplay.init(AMPLITUDE_API_KEY, {
    deviceId: "<string>",
    sessionId: "<string | number>",
    sampleRate: "<number>"
    //...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 지원팀에 문의하십시오.

구성

세션 리플레이 SDK를 초기화할 때 다음 구성 옵션을 전달하십시오.

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

화면상의 데이터 마스킹

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

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:

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.

// 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].

사용자 옵트아웃

세션 리플레이는 옵트아웃 구성 옵션을 제공합니다. 초기화의 일부로 전달될 경우 이는 Amplitude가 세션 리플레이를 수집하지 못하도록 방지합니다. 예를 들면 다음과 같습니다.

// Pass a boolean value to indicate a users opt-out status
await sessionReplay.init(AMPLITUDE_API_KEY, {
  optOut: true,
}).promise;

콘텐츠 보안 정책(CSP)

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

필수 CSP 지시어

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

CSP 지시어 참조

API 엔드포인트

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

CSP 헤더 예제

미국 데이터 센터의 경우:

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:;

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;

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

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

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

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

리플레이 수집 비활성화

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

• 사용자가 귀하의 사이트를 떠납니다.
• 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;

Data retention

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

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가 사용자를 위해 리플레이용으로 수집한 세션에 대한 정보를 제공하는 [Amplitude] Session Replay ID속성이 포함됩니다.

{
 "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.

알려진 제한 사항

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

• 세션 리플레이는 여러 프로젝트에 걸쳐 단일 사용자의 재생을 함께 연결하지 않습니다. 예를 들면 다음과 같습니다.
  • 마케팅 사이트와 웹 애플리케이션을 각각 세션 리플레이가 활성화된 별도의 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 스타일이 재생에 나타나지 않습니다.

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

• 사이트의 자산이 이동되거나 이름이 변경됩니다. 이 문제는 응용 프로그램의 새 버전을 배포할 때 발생할 수 있습니다.
• 사이트의 자산이 Amplitude의 접근을 차단하는 액세스 제어의 제한을 받고 있습니다.

CSS 로딩 문제를 해결하는 데 도움이 되는 방법:

• 도메인에 공개적으로 액세스할 수 있는지 확인하십시오. localhost에 자산을 저장한 경우 해당 자산을 준비 환경으로 이동해 보십시오.
• CDN은 오래된 재생에 대한 오래된 스타일시트를 계속 추적해야 합니다. 동일한 스타일시트의 콘텐츠가 시간별로 변경되는 경우 자산 URL에 고유한 문자열이나 해시를 추가해 보십시오. 예를 들어 stylesheet.css?93f8b89.
• 서버의 CORS 구성이 허용하는 도메인 목록에 app.amplitude.com또는 app.eu.amplitude.com를 추가합니다.

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.

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.

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일)보다 오래된 리플레이.