セッションリプレイ Android Standalone SDK

この記事では、スタンドアロン SDK を使用して Android 用セッションリプレイをインストールする方法について説明します。製品内分析にAmplitude以外のプロバイダーを使用している場合は、このオプションを選択してください。 アプリがすでにAmplitude Android SDKを使用している場合は、代わりにセッションリプレイ Android SDKプラグインを使用してください。

問題の報告

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

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

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

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

前提条件

セッションリプレイ Standalone SDKには以下が必要です。

  1. このアプリケーションはAndroidベースです。
  2. タイムスタンプまたはカスタム文字列セッションIDを使用してセッションを追跡しており、SDKに渡すことができること。セッション識別子が変更されるたびに、SDKに通知してください。
  3. デバイスIDをSDKに提供できること。
  4. スタンドアロンSDKに渡すセッションIDとデバイスIDは、Amplitudeに送信した分析イベントのIDと一致します。

スタンドアロンSDKはセッション管理機能を提供しません。アプリケーションまたはサードパーティの連携で、Session IDおよびDevice IDに対する変更を反映してSDKを更新する必要があります。

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

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

クイックスタート

最新バージョンのセッションリプレイSDKをプロジェクトの依存関係に追加します。

kotlin
implementation("com.amplitude:session-replay-android:1.1.0")

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

  1. val sessionReplay = SessionReplay()オブジェクトを作成し、リプレイの収集を開始します。API キー、セッション識別子、デバイス識別子を渡します。
  2. セッションまたはデバイス識別子が変更された場合は、sessionReplay.setSessionIdまたはsessionReplay.setDeviceIdを使用して新しい値をAmplitudeに渡します。文字列のセッションIDの場合は、代わりにsessionReplay.setCustomSessionIdを使用します。カスタムセッション ID を参照してください。
kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics
// Initialize the standalone session replay SDK
val sessionReplay = SessionReplay(
    apiKey = "api-key",
    context = applicationContext,
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    sampleRate = 1.0,
)
// Handle session ID change
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.setSessionId(ThirdPartyAnalytics.getSessionId())
// Handle device ID change
// When the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
//Update the device ID in session replay
sessionReplay.setDeviceId(ThirdPartyAnalytics.getDeviceId())

設定

セッションリプレイ SDK を初期化する際に、次の設定オプションを渡します。

カスタムセッションID

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

コンストラクタは数値のsessionIdのみを受け入れます。文字列値を使用するには、-1をsessionIdとして渡し、次にsetCustomSessionIdを呼び出します。セッションリプレイは、有効なセッション ID を設定するまでキャプチャを行いません。

kotlin
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    context = applicationContext,
    deviceId = "device-id",
    sessionId = -1,
    sampleRate = 1.0,
)
// Set a string session ID instead of the numeric sessionId
sessionReplay.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")
// Whenever your custom session changes
sessionReplay.setCustomSessionId(ThirdPartyAnalytics.getCustomSessionId())

数値sessionIdとカスタムセッション ID は同じ基本値の 2 つのビューであり、SDK はこれを文字列として保存します。

  • setSessionIdを呼び出すと、現在のカスタムセッションIDが数値に置き換えられます。カスタムセッションIDを使用する場合は、セッションが変更されるたびにsetSessionId の代わりにsetCustomSessionIdを呼び出してください。
  • 格納されている値が数値でない場合、getSessionIdは-1を返します。現在の値を読み取るには、getCustomSessionIdを呼び出します。
  • 別の値を設定すると、現在の再生が終了し、新しい再生が開始されます。

セッションリプレイがカスタムセッションと確実に一致するためには、カスタムセッション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")
}

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

ユーザーのオプトアウト

セッションリプレイにはオプトアウト設定オプションがあります。Amplitudeがセッションリプレイを収集しないようにするには、初期化時にoptOut = trueを渡します。例えば:

kotlin
// Pass a boolean value to indicate a users opt-out status
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    optOut = true,
    /* other session replay options */
)

SDKを再起動せずにキャプチャを一時停止または再開するには、実行時にsetOptOutを呼び出します:

kotlin
// Pause capture
sessionReplay.setOptOut(true)
// Resume capture
sessionReplay.setOptOut(false)
// Check the current opt-out state
val isOptedOut = sessionReplay.getOptOut()

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

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

kotlin
// Set serverZone to EU
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    serverZone = ServerZone.EU,
    /* other session replay options */
)

サンプリングレート

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

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

kotlin
// This configuration samples 1% of all sessions
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    sampleRate = 0.01,
    /* other session replay options */
)

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

セッションリプレイが開始された後、次のいずれかの時点でアプリ内で実行されます。

  • ユーザーがアプリを離れる。
  • sessionReplay.stop()呼び出します。
  • インスタンスを破棄するには、sessionReplay.shutdown()を呼び出します。

ユーザーがアプリの制限付きエリアに移動する前にsessionReplay.stop()を呼び出して、ユーザーがそのエリアにいる間のリプレイ収集を一時停止します。戻ったときに再開するには、sessionReplay.start()を呼び出します。両方のメソッドは同じインスタンスで動作します。

セッションリプレイを完全に破棄するには、sessionReplay.shutdown()を呼び出し、その後新しいインスタンスを作成して再度開始してください。

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

kotlin
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    context = applicationContext,
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    autoStart = false,
)
// Start capture when the user enters a screen you want to record
sessionReplay.start()
// Stop capture when the user leaves that screen
sessionReplay.stop()

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

kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics
val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    sampleRate = 1.0,
    /* other session replay options */
)

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

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] 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のバージョン
  • エラーメッセージまたはログ(ある場合)

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

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.

このページでは