セッションリプレイAndroidミドルウェア
早期アクセスSDK
Alphaリリースであるため、このSDKにはバグが含まれていたり、クラッシュが発生したりする可能性があります。本番環境で有効にする前に、管理された環境でアプリを十分にテストしてください。開発者向けプレビューSDKのベストプラクティスについての詳細は、SDKのメンテナンスとサポートを参照してください。
この記事では、Android SDK ミドルウェアを使用して セッションリプレイ をインストールする方法について説明します。アプリがすでに(メンテナンス用の)Amplitude SDKを使用している場合は、このオプションを使用してください。
アプリがすでに(最新の)Amplitude Android SDKを使用している場合は、セッションリプレイ Android SDKプラグインを使用してください。
製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。
セッションリプレイとパフォーマンス
Amplitudeは、インストール先のAndroidアプリのパフォーマンスへの影響を最小限に抑えるためにセッションリプレイを構築しました。
- メインユーザーインターフェースのスレッドをブロックしないように、リプレイデータを非同期にキャプチャして処理します。メインスレッドはビュー階層を分析する必要がありますが、スナップショットキャプチャのスケジュール設定と余分な処理はバックグラウンドにオフロードされます。
- バッチ処理と軽量圧縮を使用して、ネットワーク接続数と帯域幅を削減します。
- ビュー階層の処理を最適化します。階層の処理に問題が発生した場合は、Amplitudeにお問い合わせください。
始める前に
セッションリプレイミドルウェアには以下が必要です。
- アプリケーションはAndroidをターゲットとしています。
- (メンテナンス)Amplitude Android SDKの
2.40.1以上を使用していること。 - デバイスIDをSDKに提供できること。
サポートされているAndroidバージョン
セッションリプレイは、最小SDK 21(minSdk = 21)のAndroid 5.0までをサポートしています。GoogleのAndroid Studioにおける配信データによると、世界中のAndroidデバイスの99.6%以上がサポートされるはずです。
クイックスタート
最新バージョンのセッションリプレイミドルウェアをプロジェクトの依存関係に追加してください。
// 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)")
アプリケーションコードを設定します。
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() }
設定
セッションリプレイミドルウェアを初期化する際には、次のオプションを渡します。
| オプション | タイプ | 必須 | デフォルト | 概要 |
|---|---|---|---|---|
amplitude | AmplitudeClient | はい | 該当なし | 接続先となるメンテナンスAmplitude SDKクライアントインスタンス。 |
sampleRate | Number | いいえ | 0.0 | Amplitudeがリプレイ収集のために選択するセッション数を制御します。 0から1までの小数(例:0.4)を使用すると、多数のセッションの中から40%のセッションが選択されます。 |
enableRemoteConfig | Boolean | いいえ | true | このセッションリプレイのインスタンスに対するリモートコンフィギュレーションを有効または無効にします。 |
privacyConfig | PrivacyConfig | いいえ | PrivacyConfig() | どのビューをマスクするかを制御するプライバシー設定。 マスクレベルはPrivacyConfig(maskLevel = MaskLevel.MEDIUM)で設定します。マスクレベルを参照してください。 |
autoStart | Boolean | いいえ | true | ミドルウェアの初期化時に自動的にスクリーンキャプチャを開始します。 |
bandwidthLimitBytes | Int? | いいえ | null | 詳細設定従量制(携帯電話など)接続での毎日のアップロード制限(バイト単位)。 |
storageLimitMB | Int? | いいえ | null | 詳細設定ローカルストレージの制限値(MB単位)。 |
serverUrl | String? | いいえ | null | 詳細設定プロキシの完全なアップロードURL。サーバーゾーンを上書きします。 SessionReplayMiddleware.Builder(バージョン0.33.0以降)で設定します。 |
recordLogOptions.logCountThreshold | Int | いいえ | 1000 | セッションごとのログの最大数。 |
recordLogOptions.maxMessageLength | Int | いいえ | 2000 | ログメッセージの最大長です。 |
画面上のデータをマスクする
セッションリプレイ SDKを使用すると、4通りの方法でユーザー入力、テキスト、およびその他のビューコンポーネントをマスクすることができます。
マスクレベル
Android向けセッションリプレイは、3つのマスキングレベルをサポートしています。これらのレベルはprivacyConfigオプションでPrivacyConfig(maskLevel = MaskLevel.MEDIUM)を使用して設定します。デフォルトのレベルはmediumです。
セッションリプレイの設定でこのオプションを使用します。
| マスクレベル | 概要 |
|---|---|
light | パスワード、メールアドレス、電話番号の入力フィールドをマスクします。 SDK 0.26.2以降では、lightによって機密性の高いオートフィルヒント(クレジットカード番号、有効期限、セキュリティコード、名前、ユーザー名、郵便番号、コード)を含むフィールドもマスクされます。オートフィルヒントの検出にはAndroid 8.0(API 26)以降が必要です。middleware-session-replay-androidアーティファクトなどのそれ以前のバージョンでは、上記の入力フィールドタイプのみをマスクします。 |
medium(デフォルト) | lightがマスクするものすべてと、すべての編集可能なテキストフィールド(EditText)。 |
conservative | mediumがマスクするものすべてと、すべてのテキストビュー(TextView)。 |
レイアウトXML内のプライバシータグ
このオプションは、お使いのアプリケーションのレイアウトXMLで使用します。
| ビュー | 概要 |
|---|---|
<EditText> | セッションリプレイはデフォルトですべてのテキスト入力フィールドをマスクします。 ユーザーが入力フィールドにテキストを入力すると、セッションリプレイはテキストの代わりにアスタリスクをキャプチャします。 テキスト入力のマスクを解除するには、amp-unmaskタグを追加します。例:<EditText android:tag="amp-unmask" android:text="Unmask this">。 |
<TextView> | 入力要素以外の要素内のテキストをマスクするには、amp-maskタグを追加します。たとえば、<TextView android:tag="amp-mask" android:text="Mask this"/>です。 マスクされている場合、セッションリプレイはマスクされたテキストを一連のアスタリスクとしてキャプチャします。 |
| テキスト以外の要素 | テキスト以外の要素をブロックするには、タグを追加しますamp-block。 たとえば、<ImageView android:tag="amp-block"/>です。 セッションリプレイは、ブロックされた要素を同じ寸法のプレースホルダに置き換えます。 |
<WebView> | ウェブビューのマスクを解除するには、amp-unmaskタグを追加します。例:<WebView android:tag="amp-unmask"/>。 |
セッションリプレイ SDKのプライバシーメソッド
SessionReplayクラスをインポートし、アプリケーションのコードから以下のいずれかのメソッドを呼び出します。
import com.amplitude.android.sessionreplay.SessionReplay
| メソッド | 概要 |
|---|---|
unmask(view: View) | ビューのマスクを手動で解除するには、SessionReplay.unmask(view)を呼び出します。ここにあるviewはマスク対象となっている任意のビューへの参照です。 |
mask(view: View) | 入力ビュー以外のビュー内のテキストをマスクするには、SessionReplay.mask(view)を呼び出します。ここにあるviewはマスク対象となってる任意のビューへの参照です。マスクされている場合、セッションリプレイはマスクされたテキストを一連のアスタリスクとしてキャプチャします。 |
block(view: View) | テキストビュー以外のビューをブロックするには、SessionReplay.block(view)を呼び出します。ここにあるviewはブロック対象となっているビューへの参照です。セッションリプレイは、ブロックされたビューを同じ寸法のプレースホルダに置き換えます。 |
Jetpack Composeのプライバシー修飾子
コンポーザブルの場合は、レイアウトXMLタグやSessionReplayメソッドの代わりにプライバシー修飾子を使用してください。これらの修飾子には、セッションリプレイ Android SDKまたはプラグインの0.21.0バージョン以上が必要です。
必要な修飾子を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
| 修飾子 | 概要 |
|---|---|
Modifier.ampMask() | セッションリプレイがデフォルトでキャプチャするテキスト(Textコンポーザブルのコンテンツなど)をマスクします。セッションリプレイは、マスクされたテキストを一連のアスタリスクとしてキャプチャします。 |
Modifier.ampUnmask() | セッションリプレイがデフォルトでマスクするコンポーザブル(例:TextField)のマスクを解除します。 |
Modifier.ampBlock() | コンポーザブルをブロックします。セッションリプレイは、ブロックされたcomposableを同じ寸法のプレースホルダに置き換え、そのコンテンツをキャプチャしません。 |
// 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の設定に従っており、ユーザーによるオプトアウト自体をサポートしていません。
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に設定します。 例えば:
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以降で利用可能)。プロキシの要件については、「プロキシセッションリプレイのリクエスト」を参照してください。
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設定オプションを使用して、キャプチャするセッションの割合を設定します。
手動サンプリングおよび動的サンプリング、クォータの計画、クォータの集計については、セッションリプレイのサンプリングを設定するを参照してください。
// 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()を呼び出します。
// 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 実験 などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にすることもできます。たとえば、特定のユーザーグループを対象とするフィーチャーフラグを作成し、それを初期化ロジックに追加します。
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パラメータ経由で制限を設定します。
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を使用する場合は、カスタムツリーと統合できます。
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.