セッションリプレイ Flutter スタンドアロン SDK

この記事では、Flutter用セッションリプレイのインストールについて説明します。

始める前に

amplitude_session_replayパッケージの最新バージョンを使用してください。

セッションリプレイ Flutter SDK には次のことが必要です。

1. アプリケーションは iOS 13.0 以降または Android 5.0 以降（minSdk 21）で実行されます。
2. プロジェクトでは、Dart SDK 3.7.2 以降および Flutter SDK 3.29.2 以降を使用しています。
3. device IDおよびsession IDをSDKに提供できること。これらの値は、イベントプロパティとしてAmplitudeに送信する識別子と一致している必要があります。

SDK はセッション管理を提供していません。 アプリケーションまたはサードパーティの連携は、セッション ID またはデバイス ID が変更された場合に SDK を更新する必要があります。

互換性

クイックスタート

セッションリプレイをpubspec.yamlに追加します。

dependencies:
  amplitude_session_replay: ^1.0.0

次に、flutter pub getを実行します。

SessionReplayはプロセス全体のシングルトンです。SessionReplay.instanceからアクセスし、直接構築しないでください。

アプリケーションコードを設定します。

1. SessionReplayConfigを使用してSessionReplay.instance.init()を呼び出し、APIキー、デバイスID、およびセッションIDを渡します。init()は同期です。設定が保存され、メッセージチャネルハンドラをインストールします。
2. start()を呼び出して、ネイティブSDKを初期化し、録画を開始します。
3. セッションIDまたはデバイスIDが変更された場合は、setSessionId()またはsetDeviceId()を呼び出して、セッションリプレイの同期状態を維持してください。

import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // init() is synchronous: it stores the config and installs the channel handler.
  SessionReplay.instance.init(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: 'your-device-id',
      sessionId: DateTime.now().millisecondsSinceEpoch,
      sampleRate: 0.1,
    ),
  );
  // start() initializes the native SDK and begins recording.
  await SessionReplay.instance.start();
  runApp(const MyApp());
}

設定

SessionReplay.instance.init()を呼び出す際には、SessionReplayConfig経由で次のオプションを渡します。

Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

画面上のデータをマスクする

セッションリプレイにはプライバシー制御のための3つのFlutterウィジェットがあります。これらのウィジェットは、ラップされたウィジェットのサブツリー全体に適用されます。優先順位：AmpBlock > AmpMask > AmpUnmask。

プライバシーレベル

privacyConfigオプションは自動マスキング動作を制御します。

AmpMask

キャプチャされたテキストのすべての文字をアスタリスク（*）で置き換えます。これにより、元のテキストの長さとレイアウトが維持されます。 自動プライバシーレベルでは検出できない機密情報を保護するために、これを使用します。

AmpMask(
  child: Text('Sensitive information'),
)

AmpBlock

サブツリー全体を記録しないようにブロックし、プレースホルダに置き換えます。機密性の高いコンテンツにはこれを使用してください：

AmpBlock(
  child: TextField(
    decoration: InputDecoration(labelText: 'Password'),
  ),
)

AmpUnmask

プライバシーレベルの規則による自動的なマスキングを防止します。 プライバシーレベルによってマスクされるはずの内容を表示する場合に使用します。AmpUnmaskは手動によるAmpMaskまたはAmpBlockを上書きすることはできません。

AmpUnmask(
  child: Text('Public content'),
)

ユーザーのオプトアウト

ユーザをセッションリプレイの収集から除外するには、初期化時にパスするか、optOut: true実行時に呼び出す必要がありますsetOptOut(optOut: true)。 オプトアウトされたユーザーは、リプレイデータを記録したりアップロードしたりすることはありません。

await SessionReplay.instance.setOptOut(optOut: true);

EU域内のデータレジデンシー

EUのデータセンターを使用しているAmplitudeのお客様は、セッションリプレイにアクセスできます。 初期化時にserverZoneをServerZone.euに設定します。

SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    serverZone: ServerZone.eu,
  ),
);

Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's sampleRate configuration option to set the proportion of sessions to capture.

For manual and dynamic sampling, quota planning, and quota accounting, go to Configure Session Replay sampling.

SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: 'your-device-id',
    sessionId: DateTime.now().millisecondsSinceEpoch,
    sampleRate: 0.01, // Capture 1% of sessions
  ),
);

セッションIDを更新する

セッションIDが変更された場合 (たとえば、ユーザーログイン時やセッションタイムアウト時など)、セッションリプレイを更新してください。

final newSessionId = DateTime.now().millisecondsSinceEpoch;
await SessionReplay.instance.setSessionId(newSessionId);

録画の開始と停止

特定のページや機能の録画を制御します。

// Stop recording before entering a restricted area
await SessionReplay.instance.stop();
// Resume recording after leaving the restricted area
await SessionReplay.instance.start();

リプレイ収集を無効にする

セッションリプレイを有効にした後は、次のいずれかの条件までアプリ上で実行されます。

• ユーザーがアプリを離れる。
• SessionReplay.instance.stop()呼び出します。
• SessionReplay.instance.dispose()呼び出します。

ユーザーがアプリの制限付きエリアに移動する前にSessionReplay.instance.stop()を呼び出して、ユーザーがそのエリアにいる間のリプレイ収集を無効にします。

ユーザーがアプリの制限のないエリアに戻ったときに、SessionReplay.instance.start()を呼び出してリプレイ収集を再度有効にします。

ハイブリッドとadd-to-app

Flutterモジュールが、Amplitude Session Replay native SDKをすでに統合済みのネイティブiOSまたはAndroidホスト内で実行されている場合は、init()の代わりにSessionReplay.instance.attach()を呼び出してください。これによりメッセージチャネルハンドラーがインストールされ、ホストアプリのネイティブ SDK が API キー、デバイス ID、セッション ID、サンプリング、マスキング、およびアップロードのライフサイクルを所有できるようになります。 SessionReplayConfigは渡さないでください。このモードでは、ネイティブ SDK が設定を所有します。

import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  // The native SDK owns config and lifecycle. attach() only installs the
  // channel handler so native start commands reach the Flutter engine.
  SessionReplay.instance.attach();
  runApp(const MyApp());
}

ハイブリッドモードでは、ネイティブSDKが録画ライフサイクルを管理します。start()、stop()、flush()、setOptOut()、setSessionId()、およびsetDeviceId()は警告をログ出力し、何も実行しません（no-op）。これらの値はネイティブSDK上で設定してください。dispose()はDartチャネルハンドラとエンジンのみを破棄し、ネイティブSDKはそのまま残します。

アプリが複数のFlutterエンジンを実行している場合は（複数のDartエントリポイントを使用するFlutterEngineGroupなど）、各エントリポイントでattach()を呼び出します。各Flutterエンジンは独自のSessionReplay.instanceを持つ独立したisolateを実行します。

メソッド

これらのメソッドは、SessionReplay.instanceシングルトン上で呼び出します。

ライフサイクル

init()はライフサイクルごとに1回のみ実行されます。これは、初期化されていない（または廃棄済み）状態からのみ呼び出せます。新しい設定で再度初期化するには、まずdispose()を呼び出し、次にinit()を再度呼び出します。

dispose()はどの状態からでも呼び出すことができます。シングルトンを初期化されていない状態に戻すため、後でinit()またはattach()によって正常に復元されます。dispose()は永久的に破棄する場合のみ使用してください。録画を一時的に一時停止して再開するには、代わりにstop() およびstart() を使用します。

以前のベータ版からのアップグレード

バージョン0.1.0-beta.5ではインストールが簡素化され、SessionReplay APIが刷新されました。SessionReplayはプロセス全体のシングルトンとなり、SessionReplayWidgetラッパーが不要になりました。

破壊的変更

Flutter のみのアプリの場合:

ハイブリッドおよびadd-to-appの場合：

Flutter 専用アプリ

コンストラクタとSessionReplayWidgetラッパーをSessionReplay.instance.init()とstart()に置き換えます

// Before
final sessionReplay = SessionReplay(
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
await sessionReplay.start();
// After
SessionReplay.instance.init(          // synchronous, no await
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
await SessionReplay.instance.start();
runApp(const MyApp());                // no SessionReplayWidget wrapping needed

• init() ライフサイクルごとに1回限りです。 新しい設定で再初期化する前に、await SessionReplay.instance.dispose()を呼び出してください。
• セッター（setSessionId()、setDeviceId()、setOptOut()）は引き続きinit()とstart()間で機能します。

ハイブリッドとadd-to-app

プレースホルダ設定とウィジェットラッパーを1回のattach()呼び出しで置き換えます：

// Before — placeholder config + widget wrapper
return SessionReplayWidget(
  sessionReplay: SessionReplay(
    const SessionReplayConfig(
      apiKey: 'YOUR_API_KEY',
      deviceId: 'YOUR_DEVICE_ID',
      shouldInitializeNativeSDK: false,
    ),
  ),
  app: MaterialApp(...),
);
// After — one line per entry point, no config needed
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplay.instance.attach(); // native owns config and lifecycle
  runApp(const MyApp());
}

• すべてのDartエントリーポイントでattach()を呼び出します。各Flutterエンジンはそれぞれ独自の SessionReplay.instance を使用して独立しています。
• ホストアプリのネイティブSDKバージョンピン（GradleresolutionStrategy.force(...)など）をすべて削除し、Flutterプラグインが宣言した範囲内で解決できるようにします。

セッションリプレイのプロパティ

sessionReplayProperties()へのすべての呼び出しを削除します。 Amplitudeは、deviceId および sessionIdによってリプレイをアナリティクスイベントと一致させます。 これらの識別子がアナリティクスイベントとともに送信する識別子と一致していることを確認してください。 詳細については、セッションの照合を参照してください。

AmpMask、AmpUnmask 、およびAmpBlock プライバシーウィジェットは変更されていません。

Data retention, deletion, and privacy

Review consent guidance when you implement capture.

Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the Session Replay data lifecycle reference.

DSAR API

For replay metadata returned by the DSAR API, go to Session Replay DSAR metadata.

Data deletion

For user and project deletion behavior, go to Session Replay data deletion.

Bot filter

For bot filtering and property-filter restrictions, go to Session Replay bot filtering.

既知の制限事項

1. ベータ版のステータス：API は変更される可能性があります。 安定版リリース前に、互換性を損なう変更が発生する可能性があることに注意してください。
2. RSuperellipseキャプチャ: Flutter 3.32以降が必要です。基本機能はFlutter 3.29.2以降で動作します。
3. マルチビューアプリ：Flutter専用モードでは、SDKはアプリのプライマリレンダービューをキャプチャします。複数のFlutterエンジンを実行するハイブリッドおよびadd-to-app設定については、各Dartエントリポイントでattach()を呼び出します（ハイブリッドとadd-to-appを参照）。
4. リモート設定の上書き：enableRemoteConfigがtrueの場合、サーバー設定によりローカルsampleRate設定とプライバシー設定が上書きされることがあります。
5. ネイティブSDKの依存関係: iOSはAmplitudeSessionReplay~>0.12.2を使用しています。Androidはsession-replay-android[0.27.0, 0.28.0）を使用しています。

トラブルシューティング

セッションリプレイがAmplitudeに表示されない

セッションの再生は次の理由で表示されないことがあります。

• ネットワーク接続が不十分です。
• サンプリングがセッションを除外しました（sampleRate低すぎます）。
• セッションに対して、一致するdeviceIdおよびsessionIdを含むイベントが送信されていません。
• init()後のSessionReplay.instance.start()呼び出しが欠けています。

設定を確認する

1. sampleRateが0より大きいことを確認してください。デフォルトは 0.0 で、これはセッションをキャプチャしません。
2. SessionReplay.instance.init()の後にSessionReplay.instance.start()を呼び出していることを確認してください。
3. apiKey、deviceId 、sessionId がアナリティクスイベントで送信する値と一致していることを確認してください。

ネットワーク接続を確認する

アプリがインターネットにアクセスできることを確認してから、もう一度お試しください。

サンプルレートの確認

デフォルトは sampleRate です。 0.0レートをより高い数値に更新してください。 詳細については、サンプリングレートを参照してください。

セッションリプレイ処理エラー

リプレイは、取り込みから数分以内にAmplitudeに表示されます。遅延やエラーは以下の原因で発生する可能性があります：

• セッションリプレイとアナリティクス・インストルメンテーションとの間でのAPIキーまたはデバイスIDの不一致。
• セッションリプレイが間違ったプロジェクトを参照しています。
• 短いセッション。 ユーザーが初期化から数秒以内にバウンスした場合、SDKはリプレイデータをアップロードする時間がない可能性があります。