セッションリプレイ 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: ^0.1.0-beta.5

次に、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 the sampleRate configuration option to set the percentage of total sessions that Session Replay captures. For example:

To set the sampleRate consider the monthly quota on your Session Replay plan. For example, if your monthly quota is 2,500,000 sessions, and you average 3,000,000 monthly sessions, your quota is 83% of your average sessions. In this case, to ensure sampling lasts through the month, set sampleRate to .83 or lower.

Keep the following in mind as you consider your sample rate:

• When you reach your monthly session quota, Amplitude stops capturing sessions for replay.
• Session quotas reset on the first of every month.
• Use sample rate to distribute your session quota over the course of a month, rather than using your full quota at the beginning of the month.
• To find the best sample rate, Amplitude recommends that you start low, for example .01. If this value doesn't capture enough replays, raise the rate over the course of a few days. For ways to monitor the number of session replays captured, see View the number of captured sessions.
• Replays with processing errors don't count toward your monthly quota. Replays with a retention error message have already been counted against the quota, when the session was still in the retention period.

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

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests. <!--vale off-->

Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from the date of ingestion.

If you purchase extra session volume, Amplitude retains raw replay data for 90 days from the date of ingestion. If you need a more strict policy, contact Amplitude support to set the value to 30 days.

Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.

Retention periods are set at the organization level. Replays that are outside of the retention period aren't viewable in Amplitude.

DSAR API

The Amplitude DSAR API returns metadata about session replays, but not the raw replay data. All events that are part of a session replay include a [Amplitude] Session Replay ID event property. This event provides information about the sessions collected for replay for the user, and includes all metadata collected with each event.

{
  "amplitude_id": 123456789,
  "app": 12345,
  "event_time": "2020-02-15 01:00:00.123456",
  "event_type": "first_event",
  "server_upload_time": "2020-02-18 01:00:00.234567",
  "device_id": "your device id",
  "user_properties": { ... }
  "event_properties": {
    "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
  }
  "session_id": 1699922971244,
}

Data deletion

Session Replay uses Amplitude's User Privacy API to handle deletion requests. Successful deletion requests remove all session replays for the specified user.

When you delete the Amplitude project on which you use Session Replay, Amplitude deletes that replay data.

Bot filter

Session Replay uses the same block filter available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

既知の制限事項

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はリプレイデータをアップロードする時間がない可能性があります。