コンテンツにスキップ

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 を使用する場合は、2 つのプラグインが異なるバージョンのネイティブ 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 と同じです。Web セッションリプレイのアクセス方法 を参照してください。

フィードバック

このページは役に立ちましたか?