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

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

Unified SDK

Android向けUnified SDKをインストールすると、他のAmplitude製品(分析、実験)とともにセッションリプレイにアクセスできます。Unified SDKは、Amplitudeのすべての機能に単一のエントリーポイントを提供し、すべてのコンポーネントの初期化と設定を処理することで統合を簡素化します。

セッションリプレイとパフォーマンス

Amplitudeは、インストール先のAndroidアプリのパフォーマンスへの影響を最小限に抑えるためにセッションリプレイを構築しました。

  • メインユーザーインターフェースのスレッドをブロックしないように、リプレイデータを非同期にキャプチャして処理します。メインスレッドはビュー階層を分析する必要がありますが、スナップショットキャプチャのスケジュール設定と余分な処理はバックグラウンドにオフロードされます。
  • バッチ処理と軽量圧縮を使用して、ネットワーク接続数と帯域幅を削減します。
  • ビュー階層の処理を最適化します。階層の処理に問題が発生した場合は、Amplitudeにお問い合わせください。

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

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

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

問題の報告

Android用セッションリプレイに関する問題を報告される場合は、AmplitudeSessionReplay-Android GitHubリポジトリにアクセスしてください。

前提条件

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

現在のAndroid-Kotlin SDKを使用している場合は、Androidプラグインの指示に従ってください。

セッションリプレイ Androidプラグインでは以下が必要です。

  1. このアプリケーションはAndroidベースです。
  2. デバイス識別子をSDKに提供できます。

サポートされているAndroidバージョン

セッションリプレイは、最小SDK 21(minSdk = 21)のAndroid 5.0までをサポートしています。GoogleのAndroid Studioにおける配信データによると、世界中のAndroidデバイスの99.6%以上がサポートされるはずです。

クイックスタート

プラグインの最新バージョンをプロジェクトの依存関係に追加します。

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

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

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

サンプルレート

これらのコードサンプルのサンプルレートは1.0です。この設定により、Amplitudeはテスト中にセッションを確実にキャプチャしますが、本番環境で超過が発生する可能性があります。

設定

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

カスタムセッションID

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

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

kotlin
// Keep a reference to the plugin to set the custom session ID
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    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でサンプルレートとマスングレベルを設定できます。

リモート設定とテスト

enableRemoteConfigをtrueに設定すると、Amplitudeで定義した設定が、SDKでローカルに定義した設定よりも優先されます。そのため、アプリケーションのテスト中は、リモート設定を無効にして、sampleRateを1に設定し、テストセッションを確実にキャプチャできるようにする必要があります。

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

セッションリプレイ SDKを使用すると、4通りの方法でユーザー入力、テキスト、およびその他のビューコンポーネントをマスクすることができます。

マスクレベル

Android向けセッションリプレイは、3つのマスキングレベルをサポートしています。これらのレベルはprivacyConfigオプションでPrivacyConfig(maskLevel = MaskLevel.MEDIUM)を使用して設定します。デフォルトのレベルはmediumです。

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

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

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

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

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

kotlin
import com.amplitude.android.sessionreplay.SessionReplay

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

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

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

kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
kotlin
// 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設定に従います。また、プラグインインスタンス上で直接setOptOutおよびgetOptOutを呼び出すことで、SDKを再起動せずにランタイムでキャプチャを一時停止または再開することもできます。

kotlin
// Control opt-out through the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = API_KEY,
    optOut = true,
    /* other configuration */
))
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    /* session replay options */
)
amplitude.add(sessionReplayPlugin)
// Or pause and resume capture directly on the plugin instance
sessionReplayPlugin.setOptOut(true)   // pause
sessionReplayPlugin.setOptOut(false)  // resume

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

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

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

サンプリングレート

デフォルトでは、セッションリプレイはリプレイ用にセッションの0%をキャプチャします。SDKのsampleRate設定オプションを使用して、キャプチャするセッションの割合を設定します。

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

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

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

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

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

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

参照の保持

これには、SessionReplayPluginインスタンスへの参照を保持する必要があります:val sessionReplayPlugin = SessionReplayPlugin(context = applicationContext, /* session replay options */)。

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

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

kotlin
// Add the plugin without starting capture
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    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 実験 などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にすることもできます。たとえば、特定のユーザーグループを対象としたフィーチャーフラグを作成し、それを初期化ロジックに追加できます。

kotlin
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(
      context = applicationContext,
      sampleRate = 0.5
  )
  amplitude.add(sessionReplayPlugin)
}

WebViewおよびMapViewに対するサポート(ベータ版)

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

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

バージョン0.32.0以降、セッションリプレイは、キャプチャされたWebView内のウェブコンテンツにブラウザのプライバシーポリシーを適用します。WebView内の要素は、ブラウザベースのセッションリプレイに適用されるのと同じルールに従ってマスクまたはブロックされます。そのため、WebViewがキャプチャ用にマスク解除された場合でも、パスワード入力などの機密フィールドはマスクされたままです。

ログ記録

利用可能

ログ記録は、セッションリプレイAndroid 0.22.0以降で利用できます。

セッションリプレイは、Androidアプリケーションでのログ記録をサポートしています。ログ記録を有効にするには、recordLog(level, message, timestamp) API経由でログメッセージを送信し、セッションリプレイの初期化時にrecordLogOptionsパラメータ経由で制限を設定します。

kotlin
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")

セッションリプレイは、事前定義されたログレベル(Error、Warn、Log)とカスタムログレベルをサポートしています。カスタムログレベルは、任意の文字列値をRecordLogLevel(...)に渡して作成します。

ログシステムを実装している場合は、単一ポイントに変更を加えるだけでログ記録の機能を統合することができます。詳細については、次の例を参照してください。

Timber

Timberを使用する場合は、カスタムツリーと統合できます。

kotlin
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))

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

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

リテンション期間

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

DSAR API

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

データの削除

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

ボットフィルター

ボットによるフィルタリングとプロパティフィルタの制限については、セッションリプレイのボットフィルタリングを参照してください。

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

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

SDKはリプレイデータをローカルに保存します。一時的なアップロードの失敗があれば、再試行回数やストレージ制限に従って再試行します。

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

Jetpack Composeに対するサポート(アルファ版)

セッションリプレイは、Jetpack Compose for Androidアプリケーションをサポートしています。この機能は現在、アルファ版です。Jetpack Composeをセッションリプレイで使用するには、セッションリプレイAndroid SDKまたはプラグインのバージョン0.20.4以上を使用していることを確認してください。

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

既知の制限事項

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

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

    • 複数のアプリを個別のAmplitudeプロジェクトとしてインストルメントし、各プロジェクトでセッションリプレイを有効にします。
    • 既知のユーザーが1つのアプリの利用を開始し、その後別のアプリに切り替えます。
    • Amplitudeは両方のセッションをキャプチャします。
    • 各セッションのリプレイは、対応するホストプロジェクトで閲覧できます。
  • 組織がカスタムセッション定義を使用している場合、ユーザーセッションチャートにセッションリプレイは表示されません。

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

    • Canvasビュー

複数のAmplitudeインスタンス

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

トラブルシューティング

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

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

場合によっては、リプレイの長さが[Amplitude] End Sessionおよび[Amplitude] Start Sessionイベント間の時間を超えることがあります。この現象は、ユーザーがウィンドウを閉じて[Amplitude] End Sessionが発生したものの、Android SDKおよびセッションリプレイプラグインが処理を行う前に終了した場合に発生します。ユーザーがアプリを再度使用すると、SDKとプラグインがイベントを処理し、リプレイとともにAmplitudeに送信します。 このシナリオは、Client Upload TimeとEnd Session Client Event 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日)よりも古いリプレイ。

これは役に立ちましたか?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

このページでは