교차 출처 iframe 녹화

세션 리플레이 브라우저 SDK는 교차 출처 <iframe> 요소 내부의 DOM 변경사항을 캡처하여 이를 부모 페이지의 리플레이 스트림에 병합할 수 있습니다. 상위 페이지와 각 하위 iframe 페이지 모두 crossOriginIframes.enabled: true를 사용하여 SDK를 로드해야 합니다.

이 문서에서는 구성, 개인정보 보호 동작, 제한 사항 및 문제 해결에 대해 설명합니다.

작동 방식

상위 페이지에서 교차 출처 iframe 녹화를 활성화하면 SDK는 다음을 수행합니다.

1. DOM에 추가된 <iframe> 요소를 감시합니다.
2. postMessage을 통해 자식 프레임으로 start 및 stop 신호를 보냅니다.
3. 자식 rrweb 이벤트를 상위 재생 스트림으로 중계하여 재생 뷰어가 단일 세션에서 두 프레임을 모두 재구성할 수 있도록 합니다.

자식 SDK는 iframe 내에서 실행될 때 이를 감지하고 기록을 시작하기 전에 부모의 시작 신호를 기다립니다.

설정

캡처할 부모 페이지와 각 자식 iframe 페이지 모두에 세션 리플레이 SDK를 로드합니다.

상위 페이지

import * as sessionReplay from "@amplitude/session-replay-browser";
sessionReplay.init("API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});

브라우저 SDK 플러그인을 사용하는 경우 동일한 옵션을 sessionReplay.plugin()에 전달하십시오.

import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
const replay = sessionReplayPlugin({
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});
amplitude.add(replay);
amplitude.init("API_KEY", { deviceId: "DEVICE_ID" });

자식 iframe 페이지

상위 항목과 동일한 apiKey, deviceId 및 sessionId를 사용하여 SDK를 초기화하십시오. 교차 출처 iframe을 활성화하되, 자식에 coordinateChildren를 설정하지 마십시오:

import * as sessionReplay from "@amplitude/session-replay-browser";
sessionReplay.init("API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: { enabled: true },
});

iframe src을 설정할 때 iframe URL 쿼리 문자열을 통해 sessionId 및 deviceId를 자식에게 전달하십시오.

구성 옵션

개인정보 보호

하위 페이지의 rrweb 인스턴스는 자체 DOM 직렬화를 수행합니다. 상위의 개인정보 보호 설정(마스크 수준, 블록 선택기 등)은 iframe 내에 자동으로 적용되지 않습니다. 각 하위 페이지에서 개인정보 보호 설정을 개별적으로 구성하십시오.

제한 사항

• 타사 iframe(예: Stripe, Google 지도 또는 YouTube)은 캡처할 수 없습니다. 세션 리플레이 SDK를 설치하는 페이지만 제어할 수 있습니다.
• coordinateChildren: false 부모 코디네이터에서 제외됩니다. 이 모드에서는 사용자가 생애주기 분석을 직접 관리할 때까지 하위 SDK가 기록을 시작하지 않습니다.
• 동일 출처 iframe은 교차 출처 설정이 필요하지 않지만, 두 페이지 모두에서 crossOriginIframes를 활성화해도 여전히 작동합니다.

설정 유효성 검사

1. 상위 페이지와 각 하위 페이지가 crossOriginIframes.enabled: true를 사용하여 세션 리플레이 SDK를 로드하는지 확인합니다.
2. 두 페이지에서 동일한 apiKey, deviceId 및 sessionId을 사용하십시오.
3. 상위 SDK가 초기화된 후 하위 iframe을 추가하거나 탐색합니다.
4. iframe 내에서 상호작용한 다음 Amplitude의 리플레이 뷰어에서 세션을 엽니다.

로컬 교차 출처 테스트의 경우 다른 출처(다른 포트 또는 호스트 이름)에서 상위 및 하위 페이지를 제공하십시오. 공용 HTTPS 부모는 혼합 콘텐츠와 브라우저의 로컬 네트워크 액세스 제한으로 인해 http://localhost 자식을 포함할 수 없습니다.

문제 해결

라이브 페이지에서 iframe이 비어 있습니다.

재생 뷰어에서 iframe이 비어 있습니다.

관련 문서

• 세션 리플레이 브라우저 SDK 플러그인
• 세션 리플레이 독립형 SDK입니다.
• 세션 리플레이 수집 모니터링