세션 리플레이(Session Replay) 연동 방법¶

구성¶

표의 interval/cooldown 기본값은 Canvas 2D용입니다. WebGL 플러그인이 이 두 항목을 명시적으로 구성하지 않으면 더 보수적인 GPU 읽기 백 주기를 유지하여 기본적으로 readPixels 비용이 증가하는 것을 방지합니다.

표의 기본값은 low, medium, high 문자열 프리셋을 사용하지 않는 경우에 적용됩니다. 문자열 프리셋은 quality, sampling, interval, cooldown, unchanged/failure backoff 및 max-per-run을 동시에 대체합니다. 명시적인 개별 구성은 프리셋의 해당 값을 재정의합니다. 이미지 품질만 변경하려는 경우 replayCanvasQuality에 0에서 1 사이의 숫자를 전달해야 합니다. 전체 매트릭스는 Canvas 녹화 사용 설명서를 참조하세요.

Canvas 2D 녹화 구성은 SDK 3.3.0부터 사용할 수 있습니다. WebGL Replay는 SDK 3.3.7부터 제공되며, RUM 메인 패키지 버전 >= 3.3.7이 필요하고 WebGL 플러그인은 메인 패키지와 동일한 SDK 릴리스 버전을 사용하는 것을 권장합니다.

Session Replay 활성화¶

기존 SDK 도입 방식을 통해 NPM 패키지를 > 3.0.0 버전으로 교체하거나, 기존 CDN 링크를 https://static.guance.com/browser-sdk/v3/dataflux-rum.js로 교체하세요. SDK 초기화 init() 이후 Session Replay Record 데이터가 자동으로 수집되지는 않으며, startSessionReplayRecording을 실행하여 데이터 수집을 시작해야 합니다. 이는 특정 상황에서만 Session Replay Record 데이터를 수집하려는 경우에 유용합니다. 예를 들어:

// 로그인한 사용자의 작업 데이터만 수집
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

Session Replay 데이터 수집을 중지해야 하는 경우 stopSessionReplayRecording()을 호출하여 종료할 수 있습니다.

NPM¶

@cloudcare/browser-rum 패키지를 도입하고 @cloudcare/browser-rum의 버전이 > 3.0.0인지 확인하세요. 녹화를 시작하려면 초기화 후 datafluxRum.startSessionReplayRecording()을 실행하세요.

import { datafluxRum } from '@cloudcare/browser-rum'

datafluxRum.init({
  applicationId: '<DATAFLUX_APPLICATION_ID>',
  datakitOrigin: '<DATAKIT ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  trackInteractions: true,
})

datafluxRum.startSessionReplayRecording()

CDN¶

기존 CDN 주소 https://static.guance.com/browser-sdk/v2/dataflux-rum.js를 https://static.guance.com/browser-sdk/v3/dataflux-rum.js로 교체하고, DATAFLUX_RUM.init() 실행 후 DATAFLUX_RUM.startSessionReplayRecording()을 실행하세요.

<script
src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
    applicationId: '<DATAFLUX_APPLICATION_ID>',
    datakitOrigin: '<DATAKIT ORIGIN>',
    service: 'browser',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    trackInteractions: true,
})

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

오류 관련 Session Replay 데이터만 수집하는 방법 (SDK 버전 ≥3.2.19 필요)¶

기능 설명¶

페이지에서 오류가 발생하면 SDK가 자동으로 다음 작업을 수행합니다.

1. 소급 수집: 오류 발생 1분 전의 전체 페이지 스냅샷 기록
2. 지속적 녹화: 오류 발생 시점부터 세션이 종료될 때까지 지속적으로 기록
3. 지능적 보상: 독립적인 샘플링 채널을 통해 오류 케이스의 완전한 커버리지 보장

구성 예시¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// SDK 핵심 구성 초기화
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // 필수 매개변수
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

   // 환경 식별자
   service: 'browser',
   env: 'production',
   version: '1.0.0',

   // 샘플링 전략 구성
   sessionSampleRate: 100,              // 전체 기본 세션 수집 (100%)
   sessionReplaySampleRate: 0,          // 일반 화면 녹화 샘플링 비활성화
   sessionReplayOnErrorSampleRate: 100, // 오류 시나리오 100% 샘플링

   // 보조 기능
   trackInteractions: true              // 사용자 행동 추적 활성화
});

// 화면 녹화 엔진 강제 활성화 (반드시 호출)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas 녹화 설명¶

canvas 녹화는 기본적으로 자동 활성화되지 않습니다. 실제로 작동하게 하려면 최소한 다음 조건을 모두 충족해야 합니다.

• Session Replay가 샘플링되었음
• 즉, sessionReplaySampleRate > 0이거나 sessionReplayOnErrorSampleRate에 적중되었음
• startSessionReplayRecording()이 호출되었음
• replayCanvasEnabled: true가 구성되었음
• 대상 요소는 Canvas 2D여야 함. WebGL/WebGL2는 추가로 WebGL Replay 플러그인을 등록해야 함

manual 모드를 사용하는 경우, 비즈니스 코드에서 명시적으로 호출해야 합니다.

datafluxRum.snapshotCanvas(canvas)

Canvas 관련 매개변수 중 필수로 간주해야 하는 항목¶

실제 연동 시 다음 항목을 필수로 간주하는 것을 권장합니다.

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

replayCanvasMode === 'auto'인 경우 다음을 명시적으로 구성합니다.

• replayCanvasSampling
• 양수: 자동 snapshot 경로 선택, 2부터 시작 권장
• 'all': 더 높은 정확도의 자동 녹화, 그리기 프로세스 재현을 더 중요시하는 페이지에 적합
• replayCanvasAutoInterval
• 자동 snapshot의 스케줄링 간격 제어. 숫자 sampling 자체는 Canvas 2D 빈도를 제어하지 않음

세 가지 권장 최소 구성¶

수동 녹화¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

자동 snapshot¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 250,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

자동 고정확도 녹화¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CSP 시나리오¶

사이트 CSP가 worker-src blob:을 허용하지 않는 경우, 다음을 구성할 수 있습니다.

datafluxRum.init({
  // ...
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

주의할 점:

• replayCanvasWorkerUrl은 canvas snapshot 인코딩에만 영향을 미칩니다.
• workerUrl을 대체하지 않습니다.
• 모든 canvas 프레임이 canvas worker를 사용하는 것은 아닙니다.

자세한 설명은 CSP 보안 정책을 참조하세요.

Canvas 2D, WebGL/WebGL2의 전체 기능 범위, 선택적 플러그인 연동 및 성능 권장 사항은 Canvas 녹화 사용 설명서를 참조하세요. WebGL 플러그인은 RUM 메인 패키지와 동일한 SDK 버전을 사용해야 하며, WebGL 엔진이 context를 생성하거나 그리기 메서드를 캐싱하기 전에 RUM init()을 완료해야 합니다.

주의사항¶

특정 HTML 요소가 재생 시 표시되지 않음¶

세션 리플레이는 다음 HTML 요소를 지원하지 않습니다: iframe, video, audio. Session Replay는 Web Components 및 Shadow DOM을 지원하지 않습니다.

FONT 또는 IMG가 올바르게 렌더링되지 않음¶

Session Replay는 비디오가 아니라 DOM 스냅샷을 기반으로 재구성된 iframe입니다. 따라서 리플레이는 페이지의 다양한 정적 리소스(font 및 image)에 의존합니다.

다음과 같은 이유로 리플레이 시 정적 리소스를 사용할 수 없을 수 있습니다.

• 해당 정적 리소스가 더 이상 존재하지 않음. 예를 들어 이전 배포의 일부였던 경우.
• 해당 정적 리소스에 접근할 수 없음. 예를 들어 인증이 필요하거나 내부 네트워크에서만 접근 가능한 리소스일 수 있음.

• CORS(일반적으로 웹 폰트)로 인해 브라우저가 정적 리소스를 차단함.

• 리플레이는 iframe에 해당하는 guance.com 샌드박스 환경을 기반으로 하므로, 특정 정적 리소스가 특정 도메인에 권한이 부여되지 않은 경우 브라우저가 해당 요청을 차단함.

• Access-Control-Allow-Origin 헤더를 통해 guance.com가 웹사이트가 의존하는 모든 font 또는 image 정적 리소스에 접근할 수 있도록 허용하여 리플레이 시 해당 리소스에 접근할 수 있도록 보장해야 함.

자세한 내용은 교차 출처 리소스 공유를 참조하세요.

CSS style이 올바르게 적용되지 않거나 마우스 호버 이벤트가 재생되지 않음¶

font 및 image와 달리 Session Replay Record는 CSSStyleSheet 인터페이스를 활용하여 적용된 다양한 CSS 규칙을 기록 데이터의 일부로 번들링하려고 시도합니다. 이것이 실행될 수 없는 경우 CSS 파일의 링크를 기록하는 것으로 폴백됩니다.

올바른 마우스 호버 지원을 위해서는 CSSStyleSheet 인터페이스를 통해 CSS 규칙에 접근할 수 있어야 합니다.

스타일 파일이 웹 페이지와 다른 도메인에서 호스팅되는 경우, CSS 규칙에 대한 접근은 브라우저의 교차 출처 보안 검사의 적용을 받으며, 브라우저가 crossorigin 속성을 사용하여 CORS를 활용하는 스타일 파일을 로드하도록 지정해야 합니다.

예를 들어, 애플리케이션이 example.com 도메인에 있고 link 요소를 통해 assets.example.com의 CSS 파일에 의존하는 경우 crossorigin 속성을 anonymous로 설정해야 합니다.

<link rel="stylesheet" crossorigin="anonymous"
      href="https://assets.example.com/style.css">

또한 assets.example.com에서 example.com 도메인을 권한 부여해야 합니다. 이를 통해 리소스 파일이 Access-Control-Allow-Origin 헤더를 설정하여 리소스를 올바르게 로드할 수 있습니다.

더 읽어보기¶