콘텐츠로 이동

HarmonyOS 세션 리플레이(실험적)

HarmonyOS Session Replay는 ArkUI 페이지 구조, 시각적 변경 및 사용자 작업을 기록하여 페이지를 재구성하고 RUM Session, View, Error와 연결합니다. ArkWeb 페이지는 Browser SDK도 통합해야 합니다. 이 기능은 독립적인 ft_session_replay 패키지에서 제공합니다.

현재 Alpha 사전 릴리스 버전 0.1.0-alpha04이며, 기능과 API는 여전히 조정될 수 있습니다.

전제 조건

  • SDK RUM 설정을 설정 및 초기화하고 View 모니터링 수집을 활성화해야 합니다.
  • HarmonyOS Session Replay는 ft_sdk 0.1.18-alpha04 이상이 필요하며, ft_session_replay를 추가로 설치해야 합니다.
  • 자동 수집을 위해서는 Session Replay를 지원하는 @cloudcare/hvigor-ohos-plugin을 연동하고, RUM 초기화를 완료한 후 Replay를 초기화해야 합니다.
  • 애플리케이션은 HarmonyOS API 12 이상을 사용해야 하며, OHMUrl 정규화를 활성화해야 합니다. 플러그인의 현재 검증 환경은 Node.js 18+, Hvigor 6.23.5 및 HarmonyOS SDK 6.0.2(API 22)입니다.
  • 로컬 배포를 사용하는 경우 모바일 세션 리플레이 수집기 설정에 따라 리플레이 수신을 활성화해야 합니다. 공용 DataWay에는 추가 설정이 필요하지 않습니다.

설정

SDK 추가

자동 수집이 필요한 애플리케이션 모듈에 핵심 패키지와 Replay 패키지를 설치합니다:

ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_session_replay

로컬 HAR을 사용하는 경우 모듈의 oh-package.json5에서 ft_sdk.har, ft_session_replay.har의 scoped 종속성을 선언하고, 프로젝트 루트에서 overrides를 통해 Replay가 종속된 핵심 패키지가 동일한 로컬 HAR을 가리키도록 지정합니다. 설정 방식은 확장 패키지 로컬 연동과 동일합니다.

Hvigor 플러그인 추가

프로젝트 수준 hvigor/hvigor-config.json5에 빌드 플러그인을 추가합니다:

{
  "dependencies": {
    "@cloudcare/hvigor-ohos-plugin": "latest"
  }
}

애플리케이션 HAP의 hvigorfile.ts에 등록합니다:

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';

export default {
  system: hapTasks,
  plugins: [ftConsoleLogPlugin()]
};

자동 수집이 필요한 각 소스 모듈은 자체 oh-package.json5의 dependencies에 핵심 패키지와 Replay 패키지를 선언해야 합니다. 루트 디렉터리, 다른 모듈 또는 devDependencies에만 선언하면 해당 모듈의 계측이 활성화되지 않습니다. 플러그인은 지원되는 @Entry 페이지 루트 노드, 가시성, 터치, Router 전환 및 ArkUI Web 컨트롤과 controller의 연결을 자동으로 처리하며 기존 콜백을 유지합니다.

코드 호출

UIAbility.onCreate에서 핵심 SDK, RUM, Replay를 순서대로 초기화합니다. 애플리케이션 전용 filesDir을 Replay에 전달하여 캐시를 영속화합니다.

import { UIAbility } from '@kit.AbilityKit';
import {
  FTSDK, FTSDKConfig, FTRUMConfig
} from '@guancecloud/ft_sdk/Index';
import {
  FTSessionReplay, FTSessionReplayConfig,
  TouchPrivacy, ImagePrivacy, TextAndInputPrivacy
} from '@guancecloud/ft_session_replay/Index';

export default class EntryAbility extends UIAbility {
  onCreate(): void {
    FTSDK.install(FTSDKConfig.builder('YOUR_DATAKIT_URL'), this.context);
    FTSDK.installRUMConfig(new FTRUMConfig()
      .setRumAppId('YOUR_RUM_APP_ID')
      .setSessionSamplingRate(100)
      .setEnableTraceUserView(true));

    const replayConfig = new FTSessionReplayConfig()
      .setSampleRate(10)
      .setTouchPrivacy(TouchPrivacy.SHOW) // 터치 위치를 표시합니다.
      .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY) // 대형 이미지를 마스킹합니다.
      .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS) // 비밀번호 등 민감한 입력을 마스킹합니다.
      .setDelayInit(true);
    const replay = FTSessionReplay.getInstance();
    replay.init(replayConfig, this.context.filesDir);

    // 녹화를 시작합니다.
    replay.start();
  }
}

예제에서는 setDelayInit(true)를 사용하여 init() 후 start()를 호출해 녹화를 시작합니다. 설정하지 않으면 init()이 기본적으로 자동 시작됩니다.

Hvigor 플러그인을 연동하면 터치 이벤트와 Router 페이지 전환이 자동으로 수집됩니다. 사용자 정의 Navigation 전환은 ArkUI 지원을 참조하세요.

녹화를 중지하려면 replay.disable()을 호출하고, 다시 시작하려면 replay.start()를 호출합니다. 중지 후에도 이미 승인된 프레임은 계속 저장되며, 자동 업로드는 업로드 대기 중인 데이터를 계속 처리합니다. RUM 수집에는 영향을 주지 않고 기존 Replay 캐시도 지우지 않습니다.

await replay.flush()를 호출하여 즉시 업로드를 요청할 수 있습니다. 데이터는 애플리케이션 전용 디렉터리에 저장되며, Replay 패키지는 이 파일들을 추가로 암호화하지 않습니다.

메서드 이름 유형 필수 의미
setSampleRate number 아니요 Session Replay 샘플링 비율을 설정합니다. 값 범위는 [0,100]이며 0은 수집 안 함, 100은 전체 수집, 기본값은 100이고 소수를 지원합니다
setSessionReplayOnErrorSampleRate number 아니요 오류 녹화 샘플링 비율을 설정하며, 일반 녹화에 선택되지 않은 Session에 적용됩니다. 오류 발생 전 1분간의 데이터를 로컬에 보존하고, 관련 RUM Error를 수신하면 업로드 대기열에 들어갑니다. 값 범위는 [0,100]이며 기본값은 0이고 소수를 지원합니다
setTextAndInputPrivacy TextAndInputPrivacy 아니요 텍스트 및 입력 마스킹 수준을 설정합니다. MASK_SENSITIVE_INPUTS는 일반 텍스트를 유지하고 민감한 입력을 마스킹합니다. MASK_ALL_INPUTS는 모든 입력을 마스킹합니다. MASK_ALL은 텍스트와 입력을 마스킹하며 기본값은 MASK_ALL입니다
setCaptureVisiblePassword boolean 아니요 사용자가 직접 표시한 비밀번호의 수집 허용 여부입니다. 기본값은 false이며, MASK_ALL_INPUTS, MASK_ALL에서는 여전히 마스킹됩니다
setImagePrivacy ImagePrivacy 아니요 이미지 마스킹 수준을 설정합니다. MASK_ALL은 모든 이미지를 마스킹합니다. MASK_LARGE_ONLY는 대형 이미지를 마스킹합니다. MASK_NONE은 이미지를 마스킹하지 않으며 기본값은 MASK_ALL입니다
setTouchPrivacy TouchPrivacy 아니요 터치 마스킹 수준을 설정합니다. SHOW는 터치 위치를 기록하고, HIDE는 터치 위치를 숨기며 기본값은 HIDE입니다
enableLinkRUMKeys Array<string> 아니요 지정한 RUM 컨텍스트 필드를 세션 리플레이 데이터에 연결합니다. 기본값은 빈 배열이며, 리플레이 데이터 라우팅에 사용할 수 있습니다
setDelayInit boolean 아니요 녹화 시작 지연 여부이며 기본값은 false입니다. true로 설정하면 start()를 호출해야 녹화가 시작됩니다

Replay 샘플링과 RUM 샘플링은 독립적으로 설정되며, 핵심 SDK의 원격 샘플링 설정에 의해 재정의되지 않습니다.

리플레이 프레임이 성공적으로 저장되면 연결된 네이티브 View, Action, Resource, LongTask, Error에 session_has_replay=true가 포함될 수 있습니다. Session 집계 데이터는 has_replay로 현재 세션에 리플레이 데이터가 연결되었는지 나타냅니다. 리플레이 표시는 SDK가 실제 녹화 결과에 따라 자동으로 설정하며, Replay 초기화만 완료했다고 해서 이미 사용 가능한 리플레이 데이터가 있는 것은 아닙니다.

개인정보 설정

SDK는 FTSessionReplayConfig를 통해 전역 마스킹 수준을 설정할 수 있으며, 다음을 포함합니다:

  • 이미지 마스킹 수준
  • 텍스트 및 입력 마스킹 수준
  • 터치 마스킹 수준

참고:

  • 다음 설정은 init() 전에 설정해야 하며, 세션 리플레이의 전역 수집에 적용됩니다.
  • RUM의 DataModifier, LineDataModifier는 텔레메트리 필드 마스킹에 사용됩니다. 리플레이 화면에는 이 섹션의 개인정보 설정을 사용합니다.

다음 예제의 replayConfig와 열거형은 코드 호출의 정의를 따릅니다.

이미지 마스킹

setImagePrivacy(ImagePrivacy)를 사용하여 이미지 마스킹 수준을 설정합니다.

// 대형 이미지를 마스킹합니다.
replayConfig.setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY);

텍스트 및 입력 마스킹

setTextAndInputPrivacy(TextAndInputPrivacy)를 사용하여 텍스트 및 입력 마스킹 수준을 설정합니다.

// 일반 텍스트를 유지하고 비밀번호 등 민감한 입력을 마스킹합니다.
replayConfig.setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS);

직접 표시한 비밀번호의 수집을 허용하려면 페이지에서 showPassword를 onSecurityStateChange와 동기화된 상태에 바인딩해야 합니다. setCaptureVisiblePassword(true)만 활성화한다고 해서 텍스트 개인정보 정책이 재정의되지는 않습니다.

터치 마스킹

setTouchPrivacy(TouchPrivacy)를 사용하여 터치 위치 마스킹 여부를 설정합니다.

// 터치 위치를 기록합니다.
replayConfig.setTouchPrivacy(TouchPrivacy.SHOW);

Webview 세션 리플레이

ArkWeb은 다음 조건을 동시에 충족해야 합니다:

  1. 네이티브 RUM에서 setEnableTraceWebView(true)를 활성화하고, WebView 데이터 모니터링에 따라 FTWebViewHandler를 연동합니다.
  2. 네이티브 Replay가 초기화 및 시작되었고, Hvigor 플러그인을 통해 Web 컴포넌트와 controller가 연결되어야 합니다.
  3. 웹 페이지에 네이티브 Replay Bridge를 지원하는 Browser SDK를 통합하고, 웹 페이지에서 startSessionReplayRecording()을 호출합니다.

팁: 네이티브 Replay를 먼저 시작하고 FTWebViewHandler를 바인딩한 다음 웹 페이지 Browser SDK를 로드하는 것이 좋습니다. 웹 페이지 리플레이는 네이티브 Replay 샘플링 제어를 받으며, 개인정보 수준은 기본적으로 네이티브 Bridge에서 제공하고, 웹 페이지의 defaultPrivacyLevel 설정으로도 지정할 수 있습니다.

ArkUI 지원

지원되는 수집 내용에는 페이지 구조, 텍스트, 레이아웃, 스크롤, 지원되는 애니메이션 및 네이티브 컨트롤, 오버레이, 이미지 및 그리기 컴포넌트가 포함됩니다.

이미지 지원 범위

Image 및 ImageAnimator 이미지 컴포넌트를 지원합니다. 일반 Image 이미지는 시스템 컴포넌트 스냅샷을 통해 수집되며, 이미지가 로드되었고 컴포넌트가 표시되며 화면을 읽을 수 있어야 합니다. Base64 이미지는 인코딩된 데이터를 직접 읽을 수 있습니다.

이미지 소스 일반적인 사용 지원 설명
앱 리소스 이미지 Image($r('app.media.icon')) 컴포넌트에 표시된 이미지 화면을 자동으로 수집합니다.
로컬 파일 이미지 Image로 앱에서 접근 가능한 로컬 경로 또는 file:// 주소 로드 이미지가 로드되어 표시되면 자동으로 수집할 수 있습니다.
네트워크 이미지 Image로 HTTP(S) 이미지 주소 로드 컴포넌트에 이미 로드된 화면을 수집합니다. 로드에 실패했거나 아직 표시되지 않은 경우 해당 이미지 내용이 없습니다.
메모리 이미지 Image에서 PixelMap 사용 컴포넌트에 표시된 메모리 이미지를 자동으로 수집합니다.
드로어블 리소스 Image에서 DrawableDescriptor 사용 리소스가 이미지 컴포넌트에 성공적으로 렌더링되면 자동으로 수집할 수 있습니다.
Base64 내장 이미지 data:image/...;base64,... 이미지 인코딩 데이터 읽기를 지원합니다. 형식 및 크기 제한은 아래를 참조하세요.

자동으로 가져올 수 없는 이미지는 registerImageAsset(...)를 통해 이미지 컴포넌트 ID 또는 이미지 소스 문자열로 인코딩된 데이터를 수동으로 제공할 수 있습니다.

Base64 내장 이미지 및 수동 보충 리소스는 PNG(image/png), JPEG(image/jpeg), GIF(image/gif), WebP(image/webp), SVG(image/svg+xml)를 지원합니다. 단일 이미지 인코딩 데이터는 2 MiB를 초과할 수 없습니다. Base64 이미지는 디코딩 후 크기로 계산합니다.

그리기 컴포넌트 지원

다음 컴포넌트는 컴포넌트 스냅샷을 통해 화면 수집을 지원합니다:

분류 지원 컴포넌트
QR 코드 QRCode
캔버스 Canvas
도형 그리기 Shape, Rect, Circle, Ellipse, Line, Polygon, Polyline, Path

수집 제한

적용 범위 제한 설명
이미지 및 그리기 컴포넌트 이미지 마스킹 설정은 기본적으로 ImagePrivacy.MASK_ALL을 사용하며 화면 내용을 마스킹합니다. 그리기 컴포넌트는 TextAndInputPrivacy.MASK_ALL에서도 화면 내용이 마스킹됩니다.
컴포넌트 스냅샷 API 12~14에서는 이미지 또는 그리기 컴포넌트에 안정적인 .id(...)를 설정해야 합니다. 수집된 화면은 크기가 조정될 수 있으며 원본 해상도를 보장하지 않습니다.
애니메이션 이미지 ImageAnimator는 샘플링된 화면으로 애니메이션 변화를 기록하며 프레임 단위 복원을 보장하지 않습니다. 일반 Image 내 애니메이션 이미지도 원본 애니메이션과 완전히 동기화된다고 보장하지 않습니다.
네이티브 애니메이션 및 시각 효과 네이티브 애니메이션, 블러 소재, 텍스트 레이아웃 및 시스템 기본 전환의 재생 효과가 원본 화면과 다를 수 있습니다.
리치 텍스트 RichText는 텍스트, 단락 및 기본 스타일만 수집하며, 내부의 스크립트, HTML 이미지 또는 복잡한 Web 레이아웃은 수집하지 않습니다.
PatternLock 추가 전달 또는 명시적 콘텐츠 제공이 필요할 수 있으며, 플러그인 설치만으로 완전한 녹화를 보장할 수 없습니다.
Navigation 전환 API 15+가 필요합니다. 사용자 정의 전환은 추가 전달이 필요하며, updateNavigationTransition(...) 및 finishNavigationTransition(...)를 사용하여 진행률과 종료 상태를 전달할 수 있습니다.

고급 설정

수동 페이지 연동

import { FTSessionReplay } from '@guancecloud/ft_session_replay/Index';

@Entry
@Component
struct ReplayPage {
  private replay: FTSessionReplay = FTSessionReplay.getInstance();

  private registerReplayRoot(): void {
    this.replay.registerRoot(this.getUIContext(), 'replay-page-root', vp2px(1));
  }

  onPageShow(): void {
    this.registerReplayRoot();
  }

  onPageHide(): void {
    this.replay.unregisterRoot();
  }

  build() {
    Column() {
      Text('Session Replay');
    }
    .id('replay-page-root')
    .onAreaChange(() => this.registerReplayRoot())
    .onTouch((event: TouchEvent) => this.replay.recordTouchEvent(event))
  }
}

참고: 플러그인이 루트 노드를 자동 등록하지 않은 ArkUI 페이지는 위 예제에 따라 수동으로 연동할 수 있습니다. 페이지가 표시된 후 Replay를 시작하는 경우, 현재 페이지를 등록하기 위해 registerRoot(...)를 다시 호출해야 합니다. 하위 컴포넌트가 터치 이벤트를 가로채는 경우 recordTouchEvent(event)를 통해 전달해야 합니다. 터치 위치를 표시하려면 TouchPrivacy.SHOW를 활성화하세요.

코드 및 설정 참조

문서 평가

이 페이지가 도움이 되었나요?