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 导入。
Android 侧使用 ft-sdk:1.7.3、ft-native:1.1.3 和 ft-session-replay:0.1.6-beta01；iOS 侧使用 FTMobileSDK 1.6.5 和 FTMobileSDK/FTSessionReplay 1.6.5。
iOS 工程 Deployment Target 需要设置为 12.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 额外配置¶

确认应用 ios/Podfile 中的最低版本不低于 12.0：

platform :ios, '12.0'

更新 CocoaPods 依赖：

cd ios
pod install

如果 CocoaPods 提示 FTMobileSDK 版本或 Deployment Target 冲突，请先检查项目中是否还有其他依赖锁定了更低版本的 FTMobileSDK 或 iOS 部署版本。

代码调用¶

在 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';

推荐初始化顺序：

WidgetsFlutterBinding.ensureInitialized()
FTMobileFlutter.sdkConfig(...)
FTRUMManager().setConfig(...)
FTSessionReplayManager().setConfig(...)
使用 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,
    sampleRate: 1.0,
    enableUserResource: true,
    enableNativeAppUIBlock: true,
    enableTrackNativeCrash: true,
  );

  await FTSessionReplayManager().setConfig(
    FTSessionReplayConfig(
      sampleRate: 1.0,
      sessionReplayOnErrorSampleRate: 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(),
    );
  },
);

属性	类型	必须	含义
sampleRate	double	否	采样率，取值范围 [0,1]，0 表示不采集，1 表示全采集，默认值为 1。此采样率是 RUM 采样基础上的采样率。
sessionReplayOnErrorSampleRate	double	否	错误场景下的 Session Replay 采样率，取值范围 [0,1]，0 表示不采集，1 表示全采集，默认值为 0。
touchPrivacy	FTTouchPrivacyLevel	否	设置触控行为的隐私级别。`FTTouchPrivacyLevel.show` 显示触控行为；`FTTouchPrivacyLevel.hide` 隐藏触控行为。默认 `FTTouchPrivacyLevel.hide`。
textAndInputPrivacy	FTTextAndInputPrivacyLevel	否	设置文本和输入内容的隐私级别。`maskSensitiveInputs` 只遮蔽敏感输入；`maskAllInputs` 遮蔽所有输入内容；`maskAll` 遮蔽所有文本和输入内容。默认 `maskAll`。
imagePrivacy	FTImagePrivacyLevel	否	设置图片内容的隐私级别。`maskNone` 不遮蔽图片；`maskLargeOnly` 使用原生 SDK 的部分图片遮蔽策略；`maskAll` 遮蔽所有图片。默认 `maskAll`。
enableLinkRUMKeys	List	否	根据设置的 keys，关联 RUM Context 中对应字段至会话重放数据，可用于实现会话重放数据分流。
enableSwiftUI	bool	否	iOS：是否开启原生 SwiftUI 会话重放录制，默认 `false`。Flutter Widget 录制仍需使用 `SessionReplayCapture` 包裹视图树。

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,
);

查看会话重放¶

移动端上的会话重放与 Web 查看方式相同，可以参考 Web 会话重放访问方式。