Session Replay Android Standalone SDK

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

始める前に

Session Replay Standalone SDKには以下が必要です。

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

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

サポート対象のAndroidバージョン

セッションリプレイは、最小 SDK 21（minSdk = 21）で Android 5.0 以降をサポートしています。Android StudioにおけるGoogleのディストリビューションデータによると、これにより、世界のAndroidデバイスの99.6％以上がサポートされるはずです。

クイックスタート

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

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

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

1. val sessionReplay = SessionReplay()オブジェクトを作成し、リプレイの収集を開始します。API キー、セッション識別子、デバイス識別子を渡します。
2. セッションまたはデバイス識別子が変更された場合は、sessionReplay.setSessionIdまたはsessionReplay.setDeviceIdを使用して新しい値をAmplitudeに渡します。文字列のセッションIDの場合は、代わりにsessionReplay.setCustomSessionIdを使用します。カスタムセッション ID を参照してください。
3. sessionReplay.flushを呼び出して、セッションリプレイデータをAmplitudeに送信します。アプリが終了するかバックグラウンドに移る前に必ずflushを呼び出してください。セッションが長い場合は、メモリ使用量が多くなるのを防ぐためにflushを頻繁に呼び出してください（アルファ）。

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 = Date().time,
    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())
// Send session replay data to the server
// This should always be called before app exit
sessionReplay.flush()

設定

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

カスタムセッションID

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

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

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 でサンプルレートとマスクレベルを設定するには、リモート設定を有効にしてください。

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

セッションリプレイSDKでは、ユーザー入力、テキスト、その他のビューコンポーネントをマスクする方法が4つ用意されています。

マスクレベル

Android版セッションリプレイでは3段階のマスキングに対応しており、privacyConfig オプションで PrivacyConfig(maskLevel = MaskLevel.MEDIUM) のように設定できます。デフォルトのレベルはmediumです。

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

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

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

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

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

import com.amplitude.android.sessionreplay.SessionReplay

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

// 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を渡します。例えば：

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

EUデータレジデンシー

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

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

サンプリングレート

デフォルトでは、セッションリプレイで記録されるセッションの割合は0%です。 お使いのSDKのsampleRateキャプチャするセッションの割合を設定するための設定オプション。

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

// 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()を呼び出します。

val sessionReplay = SessionReplay(
    apiKey = API_KEY,
    context = applicationContext,
    deviceId = "device-id",
    sessionId = Date().time,
    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 Experimentなどのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にするロジックを作成することもできます。たとえば、特定のユーザーグループを対象とするフィーチャーフラグを作成し、そのフラグを初期化ロジックに追加します。

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

WebViewとMapViewのサポート（ベータ）

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

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

ログ記録

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

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はリプレイデータをローカルに保存します。再試行回数とストレージ容量の制限内で、一時的なアップロード失敗が発生した場合に再試行します。

Jetpack Composeのサポート（アルファ版）

セッションリプレイは、Androidアプリ向けのJetpack Composeに対応しています。この機能は現在アルファ版です。Jetpack Compose をセッションリプレイで使用するには、バージョン 0.20.4 セッションリプレイのAndroid SDKまたはプラグインのバージョンを使用してください。指定されたバージョン以上が必要です。

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

既知の制限事項

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

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

  • 複数のアプリを個別のAmplitudeプロジェクトとして計測し、それぞれでセッションリプレイを有効にします。
  • 既知のユーザーがあるアプリを利用し始め、その後、別のアプリに切り替えます。
  • Amplitudeは両方のセッションをキャプチャします。
  • 既知のユーザーがあるアプリを使い始め、その後、別のアプリに切り替えます。

• 組織がカスタムセッション定義を使用している場合、ユーザーセッションチャートにはセッションリプレイが表示されません。

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

  • キャンバスビュー

トラブルシューティング

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

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

一部のシナリオでは、リプレイの長さが [Amplitude] Start Session イベントと [Amplitude] End Session イベントの間の時間を超えることがあります。これは、[Amplitude] End Session が発生した後、Android SDK とセッションリプレイのプラグインがそのイベントを処理する前に、ユーザーがアプリを閉じた場合に発生します。ユーザーがアプリを再度使用すると、SDK とプラグインがイベントを処理し、リプレイと一緒にそれを Amplitude に送信します。 End Session Client Event TimeとClient Upload Timeの間に不一致が見られる場合、このシナリオが発生していることを確認できます。

Amplitudeではセッションリプレイが表示されません

セッションリプレイは、次の理由によりAmplitudeに表示されないことがあります：

• 接続の問題
• アプリのプロセスが終了するか、保留中のリプレイデータがアップロードされる前に SDK をシャットダウンすると、この問題が発生します。
• サンプリング

接続の問題

アプリがインターネットにアクセスできることを確認してから、もう一度お試しください。

サンプリング

前述のとおり、セッションリプレイのデフォルトの sampleRate は 0 です。レートをより高い値に変更してください。詳しくは、サンプリングレート。

セッションリプレイ処理エラー

一般に、リプレイはデータの取り込み後、数分以内に利用可能になります。遅延やエラーは、次のいずれかまたは複数の原因によって発生する可能性があります。

• APIキーまたはデバイスIDの不一致。この問題は、セッションリプレイと標準イベントインストルメンテーションが異なるAPIキーまたはデバイスIDを使用している場合に発生することがあります。
• セッションリプレイは間違ったプロジェクトを参照しています。
• 短いセッション。 ユーザーが初期化から数秒以内にバウンスした場合、SDKはリプレイデータをアップロードする時間がありません。
• ページの計測。 ユーザーがアクセスするすべてのページでセッションリプレイが実装されていない場合、そのユーザーのセッションが正しくキャプチャされない可能性があります。
• 設定された期間より古いリプレイデータ保持期間（デフォルトは90日です）。

問題をレポートする

上記のトラブルシューティングガイドで解決しないセッションリプレイの問題が発生した場合は、当社のGitHub リポジトリで報告してください。

課題を作成する際は、以下の情報を含めてください：

• 問題の明確な説明
• 問題を再現するための手順
• 期待される動作と実際の動
• 使用しているSDKのバージョン
• 関連するエラーメッセージやログ