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.
セッションリプレイAndroidミドルウェア
早期アクセス SDK
アルファリリースであるため、このSDKにはバグが含まれており、クラッシュを引き起こす可能性があります。本番環境で有効にする前に、管理された環境でアプリを十分にテストしてください。開発者プレビュー版SDKのベストプラクティスについて詳しくは、SDKのメンテナンスとサポートをご覧ください。
この記事では、Android SDK ミドルウェアを使用して セッションリプレイ をインストールする方法について説明します。アプリがすでに(メンテナンス用の)Amplitude SDKを使用している場合は、このオプションを使用してください。
アプリがすでに(最新の)Amplitude Android SDKを使用している場合は、セッションリプレイ Android SDKプラグインを使用してください。
製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。
セッションリプレイとパフォーマンス
Amplitudeは、インストール先のAndroidアプリのパフォーマンスへの影響を最小限に抑えるよう、セッションリプレイを設計しました。そのために、以下の対策を講じています:
- メインのUIスレッドをブロックしないよう、リプレイデータのキャプチャと処理を非同期で行います。メインスレッドはビュー階層を分析する必要がありますが、スナップショットキャプチャのスケジュール設定と余分な処理はバックグラウンドにオフロードされます。
- バッチ処理と軽量圧縮を使用して、ネットワーク接続数と帯域幅を削減します。
- ビュー階層の処理を最適化します。ビュー階層の処理に問題が発生した場合は、Amplitudeにお問い合わせください。
始める前に
セッションリプレイミドルウェアには以下が必要です。
- アプリケーションはAndroidをターゲットとしています。
- (メンテナンス)Amplitude Android SDKの
2.40.1以上を使用していること。 - デバイスIDをSDKに提供できること。
サポート対象のAndroidバージョン
セッションリプレイは、最小 SDK 21(minSdk = 21)で Android 5.0 以降をサポートしています。Android StudioにおけるGoogleのディストリビューションデータによると、これにより、世界の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単位)。 |
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 メソッドの代わりにプライバシー修飾子を使用してください。 これらの修飾子を使用するには、バージョン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
| 修飾子 | 説明 |
|---|---|
Modifier.ampMask() | セッションリプレイがデフォルトでキャプチャするテキスト(Textコンポーザブルのコンテンツなど)をマスクします。セッションリプレイは、マスクされたテキストを一連のアスタリスクとしてキャプチャします。 |
Modifier.ampUnmask() | TextField など、セッションリプレイがデフォルトでマスクしているコンポーザブルをアンマスクします。 |
Modifier.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の設定に従っており、ユーザーによるオプトアウト自体をサポートしていません。
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 */))
サンプリングレート
デフォルトでは、セッションリプレイで記録されるセッションの割合は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 Experiment などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にすることもできます。たとえば、特定のユーザーグループを対象とするフィーチャーフラグを作成し、それを初期化ロジックに追加します。
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のサポート(ベータ)
デフォルトでは、セッションリプレイはキャプチャ内のWebビューとマップビューをブロックします。これらのコンポーネントのキャプチャを有効にするには、「画面上のデータをマスク」で説明されている設定を使用します。
ウェブビューセッションリプレイは、レンダリングされたページにJavaScriptを挿入します。 これを有効にするために、SDK はマスクされていないウェブビューでjavaScriptEnabled をtrue 文脈確認が必要です。
ログ記録
提供状況
ログ記録は、セッションリプレイ Android0.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))
データのリテンション、削除、プライバシー
キャプチャを実装する際には、同意に関するガイダンスを確認してください。
データ保持期間
ネイティブSDKおよびFlutter SDKのデータ保持に関するガイダンスと変更の適用日については、セッションリプレイのデータライフサイクルに関するリファレンスをご覧ください。
DSAR API
DSAR API によって返されるリプレイのメタデータについては、セッションリプレイの DSAR メタデータをご覧ください。
データ削除
ユーザーおよびプロジェクトの削除時の動作については、セッションリプレイのデータ削除を参照してください。
ボットフィルター
ボットのフィルタリングおよびプロパティフィルターの制限については、セッションリプレイのボットフィルタリングへ移動してください。
セッションリプレイのストレージ
ユーザーがアプリでトラッキングをオプトアウトする場合、optOut 設定オプションを使用して、そのユーザーのリプレイ収集を無効にします。
SDKはリプレイデータをローカルに保存します。再試行回数とストレージ容量の制限内で、一時的なアップロード失敗が発生した場合に再試行します。
Amplitudeでは、アプリ終了ごとにセッションデータがサーバーに送信されるように、Amplitude SDK設定でamplitude.setFlushEventsOnClose(true)(デフォルト)を設定することを推奨しています。
Jetpack Composeのサポート(アルファ版)
セッションリプレイは、Androidアプリ向けのJetpack Composeに対応しています。この機能は現在アルファ版です。Jetpack Compose をセッションリプレイで使用するには、バージョン 0.20.4 セッションリプレイのAndroid SDKまたはプラグインのバージョンを使用してください。指定されたバージョン以上が必要です。
コンポーザブルでセッションリプレイがキャプチャする内容を制御するには、Jetpack Composeのプライバシー修飾子を使用します。Composeのマスキング機能を使用するには、0.21.0 以上が必要です。
既知の制限事項
セッションリプレイを実装する際は、次の制限事項に留意してください。
セッションリプレイは、複数のプロジェクトにわたって1人のユーザーからのリプレイを統合しません。 例:
- 複数のアプリを個別のAmplitudeプロジェクトとして計測し、それぞれでセッションリプレイを有効にします。
- 既知のユーザーがあるアプリを利用し始め、その後、別のアプリに切り替えます。
- Amplitudeは両方のセッションをキャプチャします。
- 既知のユーザーがあるアプリを使い始め、その後、別のアプリに切り替えます。
組織がカスタムセッション定義を使用している場合、ユーザーセッションチャートにはセッションリプレイが表示されません。
セッションリプレイは以下のAndroidビューをキャプチャできません:
- キャンバスビュー
これは役に立ちましたか?