세션 리플레이 React Native 독립형 SDK

세션 리플레이 React Native 독립형 SDK는 모바일 세션을 기록하고 Amplitude 애널리틱스 SDK 없이 Amplitude에 업로드합니다. 다른 분석 제공업체가 이미 앱을 계측했거나 Amplitude의 deviceId와 sessionId를 직접 관리하는 경우 사용하세요. 앱에서 이미 Amplitude React Native 분석 SDK를 사용하고 있는 경우, 세션 리플레이 React Native SDK 플러그인을 대신 설치하세요.

Amplitude API 키가 필요합니다. 패키지를 설치한 후 네이티브 앱을 다시 빌드하십시오. Expo Go에는 이 네이티브 모듈이 포함되어 있지 않으므로 개발 빌드 또는 사전 빌드 클라이언트를 사용하세요.

변경 로그 세부 정보를 확인하려면 GitHub의 패키지 변경 로그로 이동하십시오.

SDK 설치

npm install @amplitude/session-replay-react-native --save

빠른 시작

init()은 SDK를 구성하지만 캡처를 시작하지 않습니다. 일치하는 deviceId 및 sessionId 값을 전달한 후 start()를 호출하세요.

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
  privacyConfig: {
    maskLevel: "medium",
  },
});
await start();

리플레이를 분석 이벤트와 연계

세션 리플레이는 독립형 SDK와 분석 SDK가 동일한 deviceId 및 sessionId를 전송할 때 분석 이벤트에 대한 리플레이를 일치시킵니다. 이러한 값을 init()에 전달한 다음 두 식별자가 변경될 때마다 setDeviceId()및 setSessionId()를 호출합니다.

import {
  setDeviceId,
  setSessionId,
} from "@amplitude/session-replay-react-native";
await setDeviceId("new-device-id");
await setSessionId(Date.now());

독립형 SDK는 사용자를 대신하여 세션을 관리하지 않습니다. 앱 또는 타사 분석 연동은 두 식별자를 동기화해야 합니다.

구성

이 구성을 init()에 전달합니다.

방법

초기화

세션 리플레이 SDK를 구성합니다. 다른 세션 리플레이 메서드 전에 이 메서드를 호출합니다. init()캡처를 시작하지 않습니다.

import { init } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});

시작

세션 리플레이 녹화를 시작합니다. init() 이후, 그리고 이전에 실행된 stop() 이후 캡처를 다시 시작해야 하는 경우 이 메서드를 호출하세요.

import { start } from "@amplitude/session-replay-react-native";
await start();

중지

레코딩 세션 리플레이를 중지합니다.

import { stop } from "@amplitude/session-replay-react-native";
await stop();

setSessionId

세션 식별자를 업데이트합니다. 분석 이벤트의 세션 ID가 변경될 때마다 이 메서드를 호출하십시오.

import { setSessionId } from "@amplitude/session-replay-react-native";
await setSessionId(Date.now());

setDeviceId

장치 식별자를 업데이트합니다. 분석 이벤트의 장치 ID가 변경될 때마다 이 메서드를 호출하십시오. 장치 ID를 제거하려면 null을 전달하세요.

import { setDeviceId } from "@amplitude/session-replay-react-native";
await setDeviceId("new-device-id");
await setDeviceId(null);

getSessionId

세션 리플레이 SDK에서 현재 세션 식별자를 반환하거나, SDK를 초기화하지 않은 경우 null을 반환합니다.

import { getSessionId } from "@amplitude/session-replay-react-native";
const sessionId = await getSessionId();

setOptOut

런타임 시 옵트아웃을 업데이트합니다. 리플레이 수집을 비활성화하려면 true를 전달하세요. 샘플링 및 start()를 이미 호출했는지 여부에 따라 다시 허용하려면 false를 전달하세요.

import { setOptOut } from "@amplitude/session-replay-react-native";
await setOptOut(true);
await setOptOut(false);

플러시

보류 중인 세션 리플레이 데이터를 즉시 업로드합니다.

import { flush } from "@amplitude/session-replay-react-native";
await flush();

해제

네이티브 세션 리플레이를 종료하고 JavaScript 생애주기 분석 상태를 지웁니다. 다른 세션 리플레이 메서드 전에 init()을 다시 호출하세요.

import { init, start, teardown } from "@amplitude/session-replay-react-native";
await teardown();
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
await start();

화면상의 데이터 마스킹

세션 리플레이는 민감한 데이터나 PII가 포함된 보기를 마스킹하거나 난독화합니다. AmpMaskView로 영역을 감싸고 mask를 amp-mask, amp-unmask 또는 amp-block으로 설정하세요. AmpMaskView는 일반 View처럼 레이아웃되므로 View에서 사용하는 것과 동일한 레이아웃 스타일을 적용하세요.

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-mask">
  <Text>{title}</Text>
</AmpMaskView>;

AmpMaskView는 일반적인 React Native 레이아웃 노드이므로 View와 동일하게 레이아웃 계산에 포함되며, 레이아웃에서 제외되지 않습니다. 기존 콘텐츠를 감싸는 경우, 콘텐츠가 사용하는 크기 및 flex 스타일을 AmpMaskView 자체에 적용하세요. 예를 들어 flex: 1처럼 명시적으로 width, height 또는 alignItems을 지정합니다. 이러한 스타일이 없으면 래퍼가 축소되거나 감싸낸 영역의 크기를 조정할 수 있습니다.

뷰 마스크 해제

전역 마스킹 수준에 따라 마스킹되는 뷰의 마스킹을 해제하려면 mask를 amp-unmask로 설정하세요.

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-unmask">
  <Text>{title}</Text>
</AmpMaskView>;

블록 뷰

뷰를 동일한 치수의 빈 자리 표시자로 대체하려면 mask로amp-block 설정합니다.

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-block">
  <Text>Session Replay doesn't capture this content</Text>
</AmpMaskView>;

마스킹의 플랫폼 차이점

Android와 iOS는 서로 다른 네이티브 세션 리플레이 라이브러리를 사용해 AmpMaskView를 처리하므로, 동일한 마크업이라도 각 플랫폼에서 다르게 동작할 수 있습니다. 릴리스하기 전에 두 플랫폼에서 마스킹을 테스트하십시오.

세션 리플레이는 각 프레임을 캡처할 때 이러한 표현을 장치에 적용하므로 업로드된 재생 데이터에는 원본 텍스트나 픽셀 대신 마스크된 표현이 포함됩니다. 플레이어는 나중에 마스크된 콘텐츠를 복원할 수 없습니다.

두 플랫폼에서 영역을 모두 볼 수 있도록 하려면 해당 amp-unmask 래퍼를 모든 amp-mask 및 amp-block 영역 내에 중첩하지 않고 외부에 배치하십시오.

마스킹 수준 선택

init()에 privacyConfig.maskLevel을 설정하세요.

세션 리플레이 설정 페이지의 원격 구성은 SDK보다 우선합니다. 이 SDK는 네이티브 iOS 및 Android 세션 리플레이 라이브러리로 enableRemoteConfig전달됩니다. Amplitude의 세션 리플레이 개인정보 보호 설정에 따르면 원격 구성을 활성화했지만 로드에 실패하면 세션 리플레이가 세션을 캡처하지 않습니다.

웹 뷰 추적(베타)

기본적으로 세션 리플레이는 웹 뷰를 차단하고 이를 추적하지 않습니다. 웹 뷰를 추적하려면 AmpMaskView 내 웹 뷰를 감싸고 mask를 amp-unmask로 설정하세요.

import { AmpMaskView } from "@amplitude/session-replay-react-native";
import { WebView } from "react-native-webview";
<AmpMaskView mask="amp-unmask" style={{ flex: 1 }}>
  <WebView source={{ uri: "https://reactnative.dev/" }} style={{ flex: 1 }} />
</AmpMaskView>;

EU 데이터 상주

세션 리플레이는 EU 데이터 센터를 사용하는 Amplitude 프로젝트를 지원합니다. 초기화 중에 serverZone를 'EU'로 설정하십시오.

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  serverZone: "EU",
});
await start();

샘플링 속도

기본적으로 세션 리플레이는 0%의 세션을 캡처합니다. 기록하려는 세션의 백분율로 sampleRate설정합니다.

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
});
await start();

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

다음 할당량 세부 정보를 유의하십시오.

• 월간 세션 할당량에 도달하면 Amplitude는 재생을 위해 세션 캡처를 중단합니다.
• 세션 할당량은 매월 1일에 재설정됩니다.
• 처음에 전체 할당량을 사용하지 않고 샘플링 비율을 사용하여 월 전체에 세션 할당량을 분배하십시오.
• .01와 같은 낮은 비율로 시작하세요. 이 값이 충분한 리플레이를 캡처하지 못할 경우 며칠 동안 비율을 높이십시오. 캡처된 재생 볼륨을 모니터링하려면 캡처된 세션 수 보기로 이동하십시오.

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

사용자 옵트아웃

초기화 시 수집을 건너뛰려면 optOut를 true로 설정하세요. 나중에 이를 변경하려면 setOptOut()을 호출하세요. 단지 옵트아웃을 변경만을 위해 init()을 다시 실행하지 마세요.

import { init, setOptOut, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  optOut: true,
});
await setOptOut(false);
await start();

문제 해결

세션 리플레이가 나타나지 않습니다.

• init() 이후 start()를 호출하세요. init()이 SDK를 구성하고 캡처가 시작되지 않습니다.
• 0이 아닌 sampleRate값을 사용하거나 세션 재생 설정 페이지에서 원격 샘플링 속도를 확인하십시오.
• 분석 이벤트에서 사용하는 것과 동일한 deviceId와 sessionId를 전달하고, 변경 시 둘 다 업데이트하세요.
• 패키지를 설치한 후 네이티브 앱을 다시 빌드하세요. iOS의 경우 재구축 전에 pod install실행하십시오.
• 이 SDK를 Expo Go에서 실행하지 마십시오. 대신 개발 빌드 또는 사전 빌드 클라이언트를 생성하십시오.