콘텐츠로 이동

Flutter 세션 리플레이

사전 요구 사항

  • Flutter RUM 구성 설정 및 초기화를 완료하고 View 모니터링 수집을 활성화해야 합니다.
  • Flutter 세션 리플레이를 사용하려면 ft_mobile_agent_flutter와 ft_session_replay_flutter를 모두 설치해야 합니다.
  • ft_mobile_agent_flutter 0.5.7부터는 Session Replay 기능이 내장되지 않으므로 Session Replay API는 ft_session_replay_flutter에서 가져와야 합니다.
  • ft_mobile_agent_flutter 0.5.8을 사용할 때는 두 플러그인이 서로 다른 버전의 네이티브 SDK에 의존하지 않도록 네이티브 의존성과 호환되는 ft_session_replay_flutter 버전을 선택해야 합니다. 함께 제공되는 ft_session_replay_flutter 0.1.1은 Android ft-sdk:1.7.6, ft-native:1.1.4, ft-session-replay:0.1.9 및 iOS GuanceSDK1.6.9와 GuanceSDK/SessionReplay 1.6.9에 의존합니다.
  • ft_mobile_agent_flutter 0.5.8을 사용할 때는 iOS 프로젝트의 Deployment Target을 15.0 이상으로 설정해야 합니다.
  • RUM 초기화를 먼저 완료한 후 Session Replay를 초기화하여 app_id, session_id, view_id 등의 컨텍스트가 설정되도록 하는 것이 좋습니다.

설치

프로젝트 경로에서 다음을 실행합니다:

flutter pub add ft_mobile_agent_flutter
flutter pub add ft_session_replay_flutter

그러면 패키지의 pubspec.yaml에 의존성이 추가됩니다:

dependencies:
  ft_mobile_agent_flutter: [latest_version]
  ft_session_replay_flutter: [session_replay_version]

게시되지 않은 버전을 로컬에서 디버깅할 때는 path 의존성을 사용할 수 있습니다:

dependencies:
  ft_mobile_agent_flutter:
    path: /path/to/ft-sdk-flutter
  ft_session_replay_flutter:
    path: /path/to/ft-sdk-flutter/packages/ft_session_replay_flutter

그런 다음 아래 명령을 실행합니다:

flutter pub get

iOS 추가 구성

Core SDK 0.5.8 및 Session Replay SDK 0.1.1부터 Swift Package Manager를 지원하며 CocoaPods 연동 방식도 유지됩니다. iOS 최소 버전은 15.0입니다.

ft_mobile_agent_flutter 0.5.8을 사용할 때 CocoaPods로 연동하려면 앱의 ios/Podfile 및 Xcode Deployment Target이 15.0 이상인지 확인해야 합니다:

platform :ios, '15.0'

CocoaPods 의존성을 업데이트합니다:

cd ios
pod install

CocoaPods에서 네이티브 SDK 버전 또는 Deployment Target 충돌을 알리는 경우 먼저 이전 FTMobileSDK에 대한 직접 의존성, 다른 버전의 GuanceSDK, 또는 더 낮은 iOS 배포 버전이 있는지 확인해야 합니다. Swift Package Manager를 사용할 때는 Flutter iOS 통합에 따라 구성하고, ft_mobile_agent_flutter 0.5.8과 ft_session_replay_flutter 0.1.1 또는 이후 호환 버전을 함께 사용해야 하며, 네이티브 SDK 의존성을 수동으로 중복 추가할 필요는 없습니다.

코드 호출

Dart 코드에서 메인 패키지와 Session Replay 패키지를 모두 가져옵니다:

import 'package:ft_mobile_agent_flutter/ft_mobile_agent_flutter.dart';
import 'package:ft_session_replay_flutter/ft_session_replay_flutter.dart';

권장 초기화 순서:

  1. WidgetsFlutterBinding.ensureInitialized()
  2. FTMobileFlutter.sdkConfig(...)
  3. FTRUMManager().setConfig(...)
  4. FTSessionReplayManager().setConfig(...)
  5. SessionReplayCapture로 녹화할 Flutter 뷰 트리를 감쌉니다.
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await FTMobileFlutter.sdkConfig(
    datawayUrl: datawayUrl,
    cliToken: cliToken,
    serviceName: serviceName,
    debug: true,
  );

  await FTRUMManager().setConfig(
    androidAppId: androidAppId,
    iOSAppId: iOSAppId,
    sessionSamplingRate: 100.0,
    enableUserResource: true,
    enableNativeAppUIBlock: true,
    enableTrackNativeCrash: true,
  );

  await FTSessionReplayManager().setConfig(
    FTSessionReplayConfig(
      sessionReplaySamplingRate: 100.0,
      sessionReplayOnErrorSamplingRate: 0.0,
      touchPrivacy: FTTouchPrivacyLevel.show,
      textAndInputPrivacy: FTTextAndInputPrivacyLevel.maskSensitiveInputs,
      imagePrivacy: FTImagePrivacyLevel.maskAll,
      enableSwiftUI: false,
    ),
  );

  runApp(
    SessionReplayCapture(
      key: const ValueKey('session-replay-root'),
      child: const MyApp(),
    ),
  );
}

앱에서 MaterialApp.builder를 통해 페이지를 일괄적으로 감싸는 경우 builder에서 SessionReplayCapture를 사용할 수도 있습니다:

MaterialApp(
  builder: (BuildContext context, Widget? child) {
    return SessionReplayCapture(
      key: const ValueKey('session-replay-root'),
      child: child ?? const SizedBox.shrink(),
    );
  },
);
속성 유형 필수 의미
sessionReplaySamplingRate double 아니요 Session Replay 백분율 샘플링 비율이며 범위는 [0,100]이고 소수를 지원합니다. 기본값은 100(전체 샘플링)입니다. 0.1은 0.1%, 1은 1%를 의미합니다. RUM 세션 샘플링을 기준으로 Replay 샘플링을 수행합니다. Session Replay SDK 0.1.1부터 지원됩니다.
sampleRate double 아니요 이전 확률 구성이며 호환성을 위해 유지됩니다. RUM 세션 샘플링을 기준으로 하는 Replay 샘플링 비율이며 범위는 [0,1], 기본값은 1입니다. 0.1은 10%, 1은 100%를 의미합니다. sessionReplaySamplingRate 사용을 권장합니다.
sessionReplayOnErrorSamplingRate double 아니요 Replay 오류 보충 샘플링 백분율이며 범위는 [0,100]이고 소수를 지원합니다. 기본값은 0입니다. 정상 Replay 샘플링에 포함되지 않은 세션에 사용됩니다. Session Replay SDK 0.1.1부터 지원됩니다.
sessionReplayOnErrorSampleRate double 아니요 이전 확률 구성이며 호환성을 위해 유지됩니다. Replay 오류 보충 샘플링 확률이며 범위는 [0,1], 기본값은 0입니다. sessionReplayOnErrorSamplingRate 사용을 권장합니다.
touchPrivacy FTTouchPrivacyLevel 아니요 터치 동작의 개인정보 보호 수준을 설정합니다. FTTouchPrivacyLevel.show는 터치 동작을 표시하고, FTTouchPrivacyLevel.hide는 터치 동작을 숨깁니다. 기본값은 FTTouchPrivacyLevel.hide입니다.
textAndInputPrivacy FTTextAndInputPrivacyLevel 아니요 텍스트 및 입력 내용의 개인정보 보호 수준을 설정합니다. maskSensitiveInputs는 민감한 입력만 마스킹하고, maskAllInputs는 모든 입력 내용을 마스킹하며, maskAll은 모든 텍스트와 입력 내용을 마스킹합니다. 기본값은 maskAll입니다.
imagePrivacy FTImagePrivacyLevel 아니요 이미지 콘텐츠의 개인정보 보호 수준을 설정합니다. maskNone은 이미지를 마스킹하지 않습니다. maskLargeOnly는 Android에서 큰 콘텐츠 이미지를 마스킹하고, iOS에서는 앱 내장 이미지만 유지하며 내장되지 않은 이미지를 마스킹합니다. maskAll은 모든 이미지를 마스킹합니다. 기본값은 maskAll입니다.
enableLinkRUMKeys List<String> 아니요 기본적으로 추가 필드를 첨부하지 않습니다. 지정된 key에 따라 RUM Context의 해당 필드를 리플레이 데이터에 연결합니다. Session Replay SDK 0.1.1부터는 이미지 리소스 존재 여부 확인, 업로드 및 백엔드 라우팅에도 사용되어 데이터 분산을 구현할 수 있습니다. 필드 값은 요청과 함께 전송되므로 키와 같은 민감한 정보를 포함해서는 안 됩니다.
enableSwiftUI bool 아니요 iOS: 네이티브 SwiftUI 세션 리플레이 녹화를 사용할지 여부이며 기본값은 false입니다. Flutter Widget 녹화에는 여전히 SessionReplayCapture로 뷰 트리를 감싸야 합니다.

백분율 샘플링 마이그레이션

Session Replay SDK 0.1.1부터 지원됩니다.

샘플링 비율 매개변수 명명

Session Replay SDK 0.1.1부터는 sessionReplaySamplingRate와 sessionReplayOnErrorSamplingRate 사용을 권장하며, 값은 0~100 범위의 백분율이고 소수를 지원합니다. 0은 샘플링하지 않음을, 100은 전체 샘플링을 의미합니다. 범위를 벗어난 값, NaN 또는 무한대와 같은 유효하지 않은 값은 ArgumentError를 발생시킵니다.

이전 sampleRate와 sessionReplayOnErrorSampleRate는 계속 호환성을 위해 유지되며, 값은 0~1 범위의 확률입니다. 예를 들어 이전 필드의 0.1은 10%를, 새 필드의 0.1은 0.1%를 의미합니다. 동일한 항목에 새 필드와 이전 필드를 동시에 설정하면 명시적인 0을 포함하여 새 백분율 필드가 우선합니다.

원격 샘플링 필드의 단위와 우선순위는 Flutter 원격 구성 필드를 참조하십시오.

예를 들어 Replay 샘플링 12.5%를 다음과 같이 마이그레이션합니다:

 FTSessionReplayConfig(
-  sampleRate: 0.125,
-  sessionReplayOnErrorSampleRate: 0.0,
+  sessionReplaySamplingRate: 12.5,
+  sessionReplayOnErrorSamplingRate: 0.0,
   imagePrivacy: FTImagePrivacyLevel.maskAll,
 )

Flutter Session Replay 녹화 일시 중지 및 재개

Session Replay SDK 0.1.1부터 지원됩니다.

Session Replay 초기화가 완료된 후 FTSessionReplayManager().setCaptureActive(bool active)를 사용하여 Flutter 뷰 수집을 일시 중지하거나 재개할 수 있으며, Future<void>를 반환합니다. 초기 상태는 true입니다. false를 전달하면 일시 중지되고, true를 전달하면 재개되며, 실제 수집은 여전히 샘플링 구성 및 RUM View 연결 조건에 따라 제어됩니다.

// Flutter Session Replay 녹화 일시 중지
await FTSessionReplayManager().setCaptureActive(false);

// Flutter Session Replay 녹화 재개
await FTSessionReplayManager().setCaptureActive(true);

Add-to-App 또는 다중 엔진 시나리오에서는 네이티브 페이지를 표시하기 전에 Flutter 녹화를 일시 중지하고, Flutter 페이지가 다시 표시된 후 재개합니다. 이 스위치는 현재 Flutter 수집만 제어하며, 네이티브 페이지 녹화에는 여전히 해당 네이티브 연동 구성이 필요합니다. SDK를 완전히 종료하려면 종료 및 재초기화를 참조하십시오.

종료 및 재초기화

Core SDK 0.5.8 및 Session Replay SDK 0.1.1부터 통합 종료를 지원합니다.

await FTMobileFlutter.shutDown();

종료가 완료될 때까지 기다린 후 다시 수집해야 하는 경우 기본 SDK, RUM, Session Replay 순서로 명시적으로 다시 구성하고 Flutter 뷰 트리가 여전히 SessionReplayCapture로 감싸져 있는지 확인해야 합니다. 전체 단계는 초기화 예시를 참조하십시오. Replay 종료 메서드를 별도로 호출할 필요는 없습니다.

RUM View 연결

Session Replay 데이터는 RUM View 컨텍스트에 연결되어야 합니다. FTRouteObserver를 사용하여 페이지 전환을 자동으로 수집하거나, 사용자 정의 페이지 라이프사이클에서 FTRUMManager().starView(...)와 FTRUMManager().stopView(...)를 수동으로 호출하십시오.

MaterialApp(
  navigatorObservers: [
    FTRouteObserver(),
  ],
);

기본 SDK 또는 RUM을 초기화하지 않은 경우 Session Replay를 초기화해도 앱이 크래시되지는 않지만 업로드 가능한 리플레이 데이터는 생성되지 않습니다.

개인정보 보호 오버라이드

SessionReplayPrivacy를 사용하여 일부 Flutter 뷰 트리에 개인정보 보호 오버라이드를 설정할 수 있습니다. 개인정보 보호 오버라이드는 하위 뷰에 적용됩니다. 여러 계층의 오버라이드가 있는 경우 하위 뷰는 가장 가까운 상위 개인정보 보호 구성을 사용합니다.

SessionReplayPrivacy(
  textAndInputPrivacyLevel: FTTextAndInputPrivacyLevel.maskAll,
  imagePrivacyLevel: FTImagePrivacyLevel.maskAll,
  touchPrivacyLevel: FTTouchPrivacyLevel.hide,
  child: child,
);

WebView Session Replay

현재 Flutter Session Replay는 WebView 내 웹 페이지 콘텐츠의 세션 리플레이를 지원하지 않습니다.

세션 리플레이 보기

모바일의 세션 리플레이는 Web에서 확인하는 방식과 동일하며, Web 세션 리플레이 확인 방법을 참조할 수 있습니다.

문서 평가

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