セッションリプレイ Android プラグイン

アプリがすでにAmplitudeで計測されている場合は、Android SDKプラグインを使用してセッションリプレイをインストールしてください。製品内アナリティクスに別のプロバイダーを使用している場合は、代わりにスタンドアロンの実装を使用してください。

セッションリプレイ は、アプリケーションのビューツリーに対する変更をキャプチャします。 ビューツリーには、メインビューとすべての子ビューが再帰的に含まれています。その後、セッションリプレイ はこれらの変更を再生して、ビデオのような再生を構築します。

たとえば、セッションの開始時に、セッションリプレイ はアプリケーションのビュー ツリーの完全なスナップショットをキャプチャします。 ユーザーがアプリとやり取りする際、セッションリプレイはビューに対する各変更をdiffとしてキャプチャします。その後、セッションリプレイは各diffを元のビューツリーに順番に適用することにより、セッションのリプレイを構築します。

セッションリプレイには最大長はありません。

始める前に

使用する方法は、使用しているAmplitude Android SDKのバージョンによって異なります。

サポート対象のAndroidバージョン

セッションリプレイは、最小 SDK 21（minSdk = 21）で Android 5.0 以降をサポートしています。Android StudioにおけるGoogleのディストリビューションデータによると、これにより、世界のAndroidデバイスの99.6％以上がサポートされるはずです。

クイックスタート

// Install latest version from Maven Central
implementation("com.amplitude:plugin-session-replay-android:0.33.0")
// You will also need the Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:analytics-android:[1.29.0,2.0.0)")

import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin
// Initialize Amplitude Analytics SDK instance
val amplitude = Amplitude(
    Configuration(
        apiKey = API_KEY,
        context = applicationContext
    )
)
// Create and Install Session Replay Plugin
// Recording will be handled automatically
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0)
amplitude.add(sessionReplayPlugin)

設定

セッションリプレイプラグインを初期化する際には、次のオプションを渡してください。

カスタムセッションID

Androidバージョン0.26.4以降のセッションリプレイでは、setCustomSessionIdメソッドを通じて、UUIDなどの文字列セッションIDをサポートしています。プロジェクトでAmplitude session_idの代わりにカスタムイベントプロパティを使用してセッションを定義している場合は、カスタムセッションIDを使用してください。

カスタムセッションIDを設定する場合、この値はプラグインがAmplitude SDKから同期するセッションIDよりも優先されます。 nullを渡してオーバーライドをクリアし、AmplitudeセッションIDを使用して再開します。

// Keep a reference to the plugin to set the custom session ID
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0)
sessionReplayPlugin.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")
amplitude.add(sessionReplayPlugin)
// Whenever your custom session changes
sessionReplayPlugin.setCustomSessionId(newCustomSessionId)

セッションリプレイがカスタムセッションと確実に一致するためには、カスタムセッションIDは次の制約に従う必要があります。

• この値に/を含めることはできません。セッションリプレイは/をセッションリプレイIDの区切り文字として使用します。このIDの形式は<deviceId>/<sessionId>です。
• この値に使用できるのは、文字a-z A-Z 0-9 _ - . | @ : =のみです。
• 値は、イベント時にAmplitudeに送信するセッション定義プロパティと一致している必要があります。 詳細については、セッションの照合を参照してください。

リモート設定

Amplitude でサンプルレートとマスクレベルを設定するには、リモート設定を有効にしてください。

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

セッションリプレイSDKでは、ユーザー入力、テキスト、その他のビューコンポーネントをマスクする方法が4つ用意されています。

マスクレベル

Android版セッションリプレイでは3段階のマスキングに対応しており、privacyConfig オプションで PrivacyConfig(maskLevel = MaskLevel.MEDIUM) のように設定できます。デフォルトのレベルはmediumです。

このオプションは、セッションリプレイの設定で使用します。

レイアウトXML内のプライバシータグ

このオプションは、アプリケーションのレイアウト XML で使用します。

セッションリプレイSDKのプライバシーメソッド

SessionReplayクラスをインポートし、アプリケーションのコードから以下のいずれかのメソッドを呼び出します。

import com.amplitude.android.sessionreplay.SessionReplay

Jetpack Compose のプライバシー修飾子

コンポーザブルについては、レイアウト XML タグや SessionReplay メソッドの代わりにプライバシー修飾子を使用してください。 これらの修飾子を使用するには、バージョン0.21.0以降のセッションリプレイ Android SDKまたはプラグインが必要です。

必要な修飾子を com.amplitude.android.sessionreplay.compose からインポートし、コンポーザブルの修飾子チェーンに追加します。

import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock

// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)
// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)
// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}

プライバシー修飾子は、適用先のコンポーザブルと、その内部にネストされたすべての要素に適用されます。ネストされたコンポーザブルに独自のプライバシー修飾子がある場合、その修飾子がそのコンポーザブルとその子孫に対して優先されます。

ユーザーのオプトアウト

セッションリプレイプラグインはAndroid SDKのoptOut設定に従っており、単独ではユーザーによるオプトアウトをサポートしていません。

// Set optOut on the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = API_KEY,
    optOut = true,
    /* other configuration */
))
amplitude.add(SessionReplayPlugin(/* session replay options */))

EUデータレジデンシー

セッションリプレイは、EUのデータセンターを使用するAmplitudeのお客様が利用できます。 初期化時に serverZone 設定オプションを EU に設定します。例：

// Set serverZone on the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = API_KEY,
    serverZone = ServerZone.EU,
    /*, other configuration */
))
amplitude.add(SessionReplayPlugin(/* session replay options */))

サンプリングレート

デフォルトでは、セッションリプレイで記録されるセッションの割合は0%です。 お使いのSDKのsampleRateキャプチャするセッションの割合を設定するための設定オプション。

手動および動的サンプリング、クォータ計画、クォータ管理については、セッションリプレイのサンプリングを設定するを参照してください。

// This configuration samples 1% of all sessions
amplitude.add(SessionReplayPlugin(sampleRate = 0.01))

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

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

• ユーザーがアプリを離れる。
• sessionReplayPlugin.stop()呼び出します。
• このプラグインはamplitude.remove(sessionReplayPlugin)を使用してSDKから削除できます。

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

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

特定の画面のみをキャプチャするには、起動時に起動しないようにautoStart = falseでプラグインを初期化し、ユーザーがこれらの画面に出入りするときに、start()およびstop()を呼び出します。

// Add the plugin without starting capture
val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 1.0, autoStart = false)
amplitude.add(sessionReplayPlugin)
// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()
// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()

また、Amplitude Experiment などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にすることもできます。たとえば、特定のユーザーグループを対象としたフィーチャーフラグを作成し、それを初期化ロジックに追加できます。

import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin
// Your existing initialization logic with Android SDK
val amplitude = Amplitude(Configuration(apiKey = API_KEY /*, ... other configuration */))
if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  val sessionReplayPlugin = SessionReplayPlugin(sampleRate = 0.5)
  amplitude.add(sessionReplayPlugin)
}

WebViewとMapViewのサポート（ベータ）

デフォルトでは、セッションリプレイはキャプチャ内のWebビューとマップビューをブロックします。これらのコンポーネントのキャプチャを有効にするには、「画面上のデータをマスク」で説明されている設定を使用します。

ウェブビューセッションリプレイは、レンダリングされたページにJavaScriptを挿入します。 これを有効にするために、SDK はマスクされていないウェブビューでjavaScriptEnabled をtrue 文脈確認が必要です。

ログ記録

import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions
val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)
sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")
// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")

import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber
class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}
val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)
Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))

データのリテンション、削除、プライバシー

キャプチャを実装する際には、同意に関するガイダンスを確認してください。

データ保持期間

ネイティブSDKおよびFlutter SDKのデータ保持に関するガイダンスと変更の適用日については、セッションリプレイのデータライフサイクルに関するリファレンスをご覧ください。

DSAR API

DSAR API によって返されるリプレイのメタデータについては、セッションリプレイの DSAR メタデータをご覧ください。

データ削除

ユーザーおよびプロジェクトの削除時の動作については、セッションリプレイのデータ削除を参照してください。

ボットフィルター

ボットのフィルタリングおよびプロパティフィルターの制限については、セッションリプレイのボットフィルタリングへ移動してください。

セッションリプレイのストレージ

ユーザーがアプリでトラッキングをオプトアウトする場合、optOut 設定オプションを使用して、そのユーザーのリプレイ収集を無効にします。

SDKはリプレイデータをローカルに保存します。再試行回数とストレージ容量の制限内で、一時的なアップロード失敗が発生した場合に再試行します。

Amplitudeは、アプリ終了ごとにセッションデータをサーバーに送信するようにflushEventsOnClose = trueAmplitude SDK設定（デフォルト）で設定することを推奨しています。

Jetpack Composeのサポート（アルファ版）

セッションリプレイは、Androidアプリ向けのJetpack Composeに対応しています。この機能は現在アルファ版です。Jetpack Compose をセッションリプレイで使用するには、バージョン 0.20.4 セッションリプレイのAndroid SDKまたはプラグインのバージョンを使用してください。指定されたバージョン以上が必要です。

コンポーザブルでセッションリプレイがキャプチャする内容を制御するには、Jetpack Composeのプライバシー修飾子を使用します。Composeのマスキング機能を使用するには、0.21.0 以上が必要です。

既知の制限事項

セッションリプレイを実装する際は、次の制限事項に留意してください。

• セッションリプレイは、複数のプロジェクトにわたって1人のユーザーからのリプレイを統合しません。 例：

  • 複数のアプリを個別のAmplitudeプロジェクトとして計測し、それぞれでセッションリプレイを有効にします。
  • 既知のユーザーがあるアプリを利用し始め、その後、別のアプリに切り替えます。
  • Amplitudeは両方のセッションをキャプチャします。
  • 既知のユーザーがあるアプリを使い始め、その後、別のアプリに切り替えます。

• 組織がカスタムセッション定義を使用している場合、ユーザーセッションチャートにはセッションリプレイが表示されません。

• セッションリプレイは以下のAndroidビューをキャプチャできません：

  • キャンバスビュー

複数のAmplitudeインスタンス

セッションリプレイは、Amplitude SDKの単一インスタンスへの接続をサポートしています。アプリケーションに複数のインスタンスが実装されている場合は、プロジェクトに関連性の高いインスタンスでセッションリプレイを開始してください。

トラブルシューティング

個々のステータスとエラーの詳細については、セッションリプレイ取り込みモニターをご覧ください。 |

リプレイの長さとセッション時間が一致しません。

一部のシナリオでは、リプレイの長さが [Amplitude] Start Session イベントと [Amplitude] End Session イベントの間の時間を超えることがあります。これは、[Amplitude] End Session が発生した後、Android SDK とセッションリプレイのプラグインがそのイベントを処理する前に、ユーザーがアプリを閉じた場合に発生します。ユーザーがアプリを再度使用すると、SDK とプラグインがイベントを処理し、リプレイと一緒にそれを Amplitude に送信します。 End Session Client Event TimeとClient Upload Timeの間に不一致が見られる場合、このシナリオが発生していることを確認できます。

Amplitudeではセッションリプレイが表示されません

セッションリプレイは、次の理由によりAmplitudeに表示されないことがあります：

• 接続の問題
• アプリのプロセスが終了するか、保留中のリプレイデータがアップロードされる前に SDK をシャットダウンすると、この問題が発生します。
• サンプリング

接続の問題

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

サンプリング

前述のとおり、セッションリプレイのデフォルトの sampleRate は 0 です。レートをより高い値に変更してください。詳しくは、サンプリングレート。

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

一般に、リプレイはデータの取り込み後、数分以内に利用可能になります。遅延やエラーは、次のいずれかまたは複数の原因によって発生する可能性があります。

• APIキーまたはデバイスIDの不一致。この問題は、セッションリプレイと標準イベントインストルメンテーションが異なるAPIキーまたはデバイスIDを使用している場合に発生することがあります。
• セッションリプレイは間違ったプロジェクトを参照しています。
• 短いセッション。 ユーザーが初期化から数秒以内にバウンスした場合、SDKはリプレイデータをアップロードする時間がありません。
• ページの計測。 ユーザーがアクセスするすべてのページでセッションリプレイが実装されていない場合、そのユーザーのセッションが正しくキャプチャされない可能性があります。
• 設定された期間より古いリプレイデータ保持期間（デフォルトは90日です）。

問題をレポートする

上記のトラブルシューティングガイドで解決しないセッションリプレイの問題が発生した場合は、当社のGitHub リポジトリで報告してください。

課題を作成する際は、以下の情報を含めてください：

• 問題の明確な説明
• 問題を再現するための手順
• 期待される動作と実際の動
• 使用しているSDKのバージョン
• 関連するエラーメッセージやログ

キャプチャされたセッションには限られた情報しか含まれていません

Amplitudeは、セッションリプレイがセッションをキャプチャするときに[Amplitude] Replay Capturedイベントを自動的に作成します。実装でこのイベントが表示されない場合、ファネル分析、セグメンテーション、ジャーニーチャートなどのAmplitudeの分析ツールでリプレイが正しく表示されない可能性があります。セッションリプレイは、引き続きセッションリプレイホームページまたはユーザープロフィールページで確認できます。

このイベントが表示されない理由には、次のようなものがあります。

• ユーザーがオプトアウトしたか、現在のsampleRateによるサンプルセットに含まれていません。より多くのセッションをキャプチャするにはsampleRateを増やしてください。
• セッション用のoptOutの設定を有効にしました。 optOutおよびsampleRate設定にそのセッションが含まれていることを確認してください。
• アプリがイベントを計測するために Android SDK 以外のメソッドを使用しています。 Android 用の セッションリプレイ Standalone SDK の使用を検討してください。

これらの設定を確認してもイベントが表示されない場合は、Amplitude サポートにお問い合わせください。

リプレイの長さとセッション時間が一致しません

場合によっては、リプレイの長さが[Amplitude] Start Sessionおよび[Amplitude] End Sessionイベント間の時間を超えることがあります。この状況は、[Amplitude] End Sessionイベント発生後、Android SDK と セッションリプレイ プラグインがイベントを処理できるようになる前にユーザーがアプリを閉じた場合に発生します。ユーザーがアプリを再度使用すると、SDKとプラグインがイベントを処理し、リプレイとともにそのイベントをAmplitudeに送信します。このシナリオを検証するには、End Session Client Event TimeとClient Upload Timeの間に矛盾がないか確認してください。

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

セッション再生は、次の理由によりAmplitudeに表示されないことがあります：

• ネットワーク接続がありません。アプリがインターネットにアクセスできることを確認してから、もう一度試してみてください。
• アプリを終了する前に録画のフラッシュに失敗しています。
• 現在のセッションでは、Android SDK を介して送信されたイベントはありません。
• [Amplitude] Replay Capturedイベントがありません。 レビューでキャプチャされたセッションに含まれる情報は限られています。
• サンプリング

サンプリング

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

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

リプレイは、取り込みから数分以内に利用可能になる必要があります。 遅延やエラーは、次のいずれかまたは複数の原因によって発生することがあります。

• API キーまたはデバイス ID が一致しません。 この不一致は、セッションリプレイと標準イベント計測が異なる API キーまたはデバイス ID を使用している場合に発生します。
• セッションリプレイが間違ったプロジェクトを参照しています。
• 短いセッション。 ユーザーが初期化から数秒以内にアプリを閉じると、SDK はリプレイデータをアップロードする時間がありません。
• ページ計測。 ユーザーが訪問するすべてのページにセッションリプレイを実装していない場合、セッションが正しくキャプチャされない可能性があります。
• 設定されたリテンション期間（デフォルトは90日）よりも古いリプレイ。