セッションリプレイAndroidミドルウェア

早期アクセスSDK

Alphaリリースであるため、このSDKにはバグが含まれていたり、クラッシュが発生したりする可能性があります。本番環境で有効にする前に、管理された環境でアプリを十分にテストしてください。開発者向けプレビューSDKのベストプラクティスについての詳細は、SDKのメンテナンスとサポートを参照してください。

この記事では、Android SDK ミドルウェアを使用して セッションリプレイ をインストールする方法について説明します。アプリがすでに(メンテナンス用の)Amplitude SDKを使用している場合は、このオプションを使用してください。

アプリがすでに(最新の)Amplitude Android SDKを使用している場合は、セッションリプレイ Android SDKプラグインを使用してください。

製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。

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

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

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

始める前に

セッションリプレイミドルウェアには以下が必要です。

  1. アプリケーションはAndroidをターゲットとしています。
  2. (メンテナンス)Amplitude Android SDKの2.40.1以上を使用していること。
  3. デバイスIDを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:middleware-session-replay-android:0.26.1")
// You will also need the (maintenance) Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:android-sdk:[2.40.1,3.0.0)")

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

kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware
// Initialize (maintenance) Amplitude Analytics SDK instance
val amplitude = Amplitude.getInstance()
    .initialize(this, AMPLITUDE_API_KEY)
    // Replay events will be flushed on close as well
    // If setFlushEventsOnClose(false) you must call flush() manually
    .setFlushEventsOnClose(true)
// Create Session Replay Middleware
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0)
// Add session replay middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(sessionReplayMiddleware)
// Track events
amplitude.logEvent("Setup (maintenance) Amplitude Android SDK with session replay!")
// Send replay events to the server
amplitude.uploadEvents()
// You can also call flush() on the middleware directly to only send replay events
// sessionReplayMiddleware.flush()
// Always flush before app exit (onPause)
// override fun Activity.onPause() { sessionReplayMiddleware.flush() }

設定

セッションリプレイミドルウェアを初期化する際には、次のオプションを渡します。

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

セッションリプレイ 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の設定に従っており、ユーザーによるオプトアウト自体をサポートしていません。

kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware
// Set optOut on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, AMPLITUDE_API_KEY)
        .setOptOut(true)
amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))

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

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

kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware
// Set serverZone on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, AMPLITUDE_API_KEY)
        .setServerZone(AmplitudeServerZone.EU)
amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))

リプレイのアップロードをプロキシに送信

リプレイのアップロードを独自のサーバー経由でルーティングするには、serverUrlをSessionReplayMiddleware.Builderで設定してください(バージョン0.33.0以降で利用可能)。プロキシの要件については、「プロキシセッションリプレイのリクエスト」を参照してください。

kotlin
import com.amplitude.api.SessionReplayMiddleware
val sessionReplayMiddleware = SessionReplayMiddleware.Builder(amplitude)
    .sampleRate(1.0)
    .serverUrl("https://replay.yourdomain.com/sessions/v2/track")
    .build()
amplitude.addEventMiddleware(sessionReplayMiddleware)

サンプリングレート

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

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

kotlin
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, sampleRate = 0.01))

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

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

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

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

参照の保持

SessionReplayMiddlewareインスタンスへの参照を保持します:val sessionReplayMiddleware = SessionReplayMiddleware(/* session replay options */)。

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

特定の画面のみをキャプチャするには、起動時にミドルウェアが起動しないようにautoStart = falseでミドルウェアを初期化し、ユーザーがこれらの画面に出入りする際にstart()とstop()を呼び出します。

kotlin
// Add the middleware without starting capture
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0, autoStart = false)
amplitude.addEventMiddleware(sessionReplayMiddleware)
// Start capture when the user enters a screen you want to record
sessionReplayMiddleware.start()
// Stop capture when the user leaves that screen
sessionReplayMiddleware.stop()

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

kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware
// Your existing initialization logic with Android SDK
val amplitude = Amplitude.getInstance().initialize(this, AMPLITUDE_API_KEY)
if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Middleware
  val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 0.5)
  amplitude.addEventMiddleware(sessionReplayMiddleware)
}

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

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

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

ログ記録

利用可能

ログ記録は、セッションリプレイ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では、アプリ終了ごとにセッションデータがサーバーに送信されるように、Amplitude SDK設定でamplitude.setFlushEventsOnClose(true)(デフォルト)を設定することを推奨しています。

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ビュー

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

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.

このページでは