セッションリプレイiOSスタンドアロンSDK

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

アプリがすでにAmplitude iOS SDKを使用している場合は、代わりにセッションリプレイiOS SDKプラグインを使用してください。

Analytics-Swift SDKとAmplitude（アクション）の送信先経由でセグメントを使用する場合は、セグメントプラグインを選択してください。

始める前に

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

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

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

対応しているiOSバージョン

セッションリプレイがサポートするiOSの最小ターゲットバージョンはiOS 13です。

クイックスタート

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

dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]

.product(name: "AmplitudeSessionReplay", package: "AmplitudeSessionReplay")

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

1. SessionReplayインスタンスを作成します。APIキーと、セッション識別子およびデバイス識別子（使用可能な場合）を渡します。
2. リプレイのキャプチャを開始するためにsessionReplay.start()を呼び出します。スタンドアロンSDKは自動的にキャプチャを開始しません。そのため、デバイス識別子とセッション識別子を設定したらstart()を呼び出す必要があります。
3. セッションまたはデバイス識別子が変更された場合は、sessionReplay.sessionId（セッション）またはsessionReplay.deviceId（デバイス）を使用して新しい値をAmplitudeに渡します。文字列のセッションIDの場合は、代わりにsessionReplay.customSessionIdを使用します。カスタムセッション ID を参照してください。
4. sessionReplay.additionalEventPropertiesを使用してセッションリプレイのプロパティを収集し、他のイベントプロパティと一緒に送信します。

import AmplitudeSessionReplay
import ThirdPartyAnalytics
// Initialize the standalone session replay SDK
let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 0.1)
// Start capturing replays. The standalone SDK doesn't start automatically.
sessionReplay.start()
// Track an event
// Get session replay properties for this session
var eventProperties = event.eventProperties ?? [:]
eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current }
event.eventProperties = eventProperties
ThirdPartyAnalytics.track(event)
// Handle session ID changes
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.sessionId = ThirdPartyAnalytics.getSessionId()
// Handle device ID changes
// Whenever the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
// Update the device ID in session replay
sessionReplay.deviceId = ThirdPartyAnalytics.getDeviceId()

設定

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

カスタムセッションID

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

初期化子は数値のsessionIdのみを受け入れます。文字列値を使用するには、インスタンスを作成した後にそのインスタンスでcustomSessionIdを設定し、カスタムセッションが変更される度に更新します。

let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sampleRate: 0.1)
// Set a string session ID instead of the numeric sessionId
sessionReplay.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
sessionReplay.start()
// Whenever your custom session changes
sessionReplay.customSessionId = ThirdPartyAnalytics.getCustomSessionId()

sessionIdとcustomSessionIdは同じ基本値の2つのビューであり、SDKはその値を文字列として保存します。

• sessionIdを設定すると、現在のカスタムセッションIDが数値に置き換えられます。カスタムセッションIDを使用する場合は、セッションが変更される度にsessionIdではなくcustomSessionIdを更新してください。
• 格納されている値が数値でない場合、sessionIdプロパティは-1を返します。現在の値を取得するには、customSessionIdを読み込みます。
• 別の値を設定すると、現在の再生が終了し、新しい再生が開始されます。

セッションリプレイがカスタムセッションと確実に一致するためには、カスタムセッションIDは次の制約に従う必要があります。

• この値に/を含めることはできません。セッションリプレイは/をセッションリプレイIDの区切り文字として使用します。このIDの形式は<deviceId>/<sessionId>です。
• この値に使用できるのは、文字a-z A-Z 0-9 _ - . | @ : =のみです。
• 値は、イベント時にAmplitudeに送信するセッション定義プロパティと一致している必要があります。 詳細については、セッションの照合を参照してください。

実行時にマスキングを変更

アプリの実行中に自動マスキングレベルを変更するようにprivacyConfig設定します。

sessionReplay.privacyConfig = PrivacyConfig(maskLevel: .conservative)

リモート設定がマスクレベルを指定している場合、そのレベルが優先されます。 SDK はローカル値を保持し、Remote Config がマスキングレベルを提供しない場合や、Remote Config を無効にした場合privacyConfigに適用します。

リモート設定

Amplitude でサンプルレートとマスクレベルを設定するには、リモート設定を有効にしてください。

画面上のデータをブロックする

セッションリプレイは、機密性の高い画面上のデータをブロックするために3つの方法をサポートしています。 WebViewのマスキング設定は、WebViewのサポートセクションにあります。

マスクレベル

iOS向けセッションリプレイは、maskLevelオプションで設定可能な3つのレベルのマスキングをサポートしています。

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

UIKit のプライバシーメソッド

セッションリプレイは、プライバシーを管理するための UIView 拡張機能を提供します。セッションリプレイライブラリをインポートしてアクセスできるようにします。

import AmplitudeSessionReplay

SwiftUIのプライバシー修飾子

セッションリプレイでは、プライバシーを管理するためにViewの拡張機能を提供しています。セッションリプレイライブラリをインポートしてアクセスします。

import AmplitudeSessionReplay

ユーザーのオプトアウト

セッションリプレイにはオプトアウト設定オプションがあります。初期化中にoptOut: trueを渡すと、Amplitudeはセッションリプレイを収集しません。例えば：

// Pass a boolean value to indicate a user's opt-out status
        let sessionReplay = SessionReplay(apiKey: API_KEY,
                                             optOut: true,
                                             /* other session replay options */)

EUデータレジデンシー

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

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

サンプリングレート

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

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

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

録画品質

再生の忠実度と、パフォーマンスおよびストレージのバランスを調整するには、品質プロファイルを選択します。低いプロファイルでは、キャプチャフレームレートと画像解像度が低くなります。プロファイルが高いほど、使用されるフレームレートと解像度も高くなります。 SDKがデバイスに基づいてプロファイルを選択できるようにする場合は、QualityProfile.automaticを使用します（例：新しいデバイスでは高く、古いデバイスでは低くするなど）。

// Use automatic profile selection based on device
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .automatic,
                                     /* other session replay options */)
// Or set a fixed profile (low, medium, or high)
let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .medium,
                                     /* other session replay options */)

既存のスタンドアロン・インスタンスのプロファイルを変更することもできます。

sessionReplay.quality = .medium

従量課金制ネットワークでのアップロードを無効にする

デバイスが従量課金制ネットワークに接続されている間は、セッションリプレイのアップロードを一時停止し、ユーザーのモバイルデータの使用を避けてください。セッションリプレイは引き続きデータをローカルに記録します。デバイスがWi-Fi、またはその他の従量制ではない接続に再接続されると、アップロードが再開されます。

let sessionReplay = SessionReplay(apiKey: API_KEY,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     uploadConfig: UploadConfig(disableMeteredUploads: true),
                                     /* other session replay options */)

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

セッションリプレイを有効にした後は、次のいずれかの条件までアプリ上で実行されます。

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

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

ユーザーがアプリの制限のないエリアに戻ったときに、sessionReplay.start()を呼び出してリプレイ収集を再度有効にします。start()およびstop()は同じインスタンス上でキャプチャの再開と一時停止を行うため、画面の切り替え時にこれらを呼び出すことで、選択した画面のみを録画することができます。

記録されたデータをフラッシュする

スタンドアロン SDK に記録されたリプレイデータをフラッシュするよう要求するには、flush()を呼び出します。 これは、ホストアナリティクスクライアントがフラッシュされるときに、同時にセッションリプレイをフラッシュしたい場合に便利です。

sessionReplay.flush()

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

import AmplitudeSessionReplay
import ThirdPartyAnalytics
let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 1.0)
if (nonEUCountryFlagEnabled) {
    sessionReplay.start()
}

Web View のサポート（ベータ版）

デフォルトでは、セッションリプレイはキャプチャ時に WebView をブロックします。すべてのWebViewコンポーネントのキャプチャを有効にするには、セッションリプレイ設定でcaptureWebViewsをtrueに設定します。

特定の WebView コンポーネントをマスクするには、画面上のデータをブロックする で説明されているプライバシーメソッドを使用してください。

// UIKit
webView.amp_isBlocked = false

マップビューのサポート（アルファ版）

セッションリプレイは、iOS アプリでのマップビューのキャプチャに対応しています。マップビューのキャプチャを有効にするには、実装でマップビューのマスクを解除してください。

// UIKit
mapView.amp_isBlocked = false
// SwiftUI
Map().amp_setBlocked(false)

ログの記録

import AmplitudeSessionReplay
let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
sessionReplay.recordLog(level: .error, message: "This is an error log")

class AmplitudeLogRecordLogger: DDAbstractLogger {
    private weak var plugin: SessionReplayPlugin?
    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }
    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)
DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}

データのリテンション、削除、プライバシー

キャプチャを実装する際には、同意に関するガイダンスを確認してください。

データ保持期間

ネイティブSDKおよびFlutter SDKのデータ保持に関するガイダンスと変更の適用日については、セッションリプレイのデータライフサイクルに関するリファレンスをご覧ください。

DSAR API

DSAR API によって返されるリプレイのメタデータについては、セッションリプレイの DSAR メタデータをご覧ください。

データ削除

ユーザーおよびプロジェクトの削除時の動作については、セッションリプレイのデータ削除を参照してください。

ボットフィルター

ボットのフィルタリングおよびプロパティフィルターの制限については、セッションリプレイのボットフィルタリングへ移動してください。

セッションリプレイのストレージ

ユーザーがアプリ内でのトラッキングをオプトアウトした場合は、optOut設定オプションを使用して、そのユーザーのリプレイデータの収集を無効にします。

セッションリプレイは、リプレイデータをアップロードする前に、ファイルシステムに一時的に保存します。初期化のたびに、最も古いリプレイデータが削除され、ディスク使用量が上限以下に抑えられます。

既知の制限事項

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

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

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

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

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

  • SFSafariViewControllerなどのプロセス外で動作するiOSビュー
  • AVPlayerLayerを使用するビュー

トラブルシューティング

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

複数のAmplitudeインスタンス

セッションリプレイは、Amplitude SDKの単一のインスタンスへのアタッチをサポートしています。アプリケーションに複数のインスタンスが実装されている場合は、プロジェクトに関連性の最も高いインスタンスでセッションリプレイを開始してください。

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

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

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

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

• 接続の問題
• 現在のセッションでは、iOS SDKを介してトリガーされたイベントはありません。
• サンプリング

接続の問題

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

現在のセッションでは、iOS SDKを介してトリガーされたイベントはありません。

セッションリプレイを利用するには、ユーザーのセッション内の少なくとも1つのイベントに [Amplitude] Session Replay ID プロパティが含まれている必要があります。Amplitude以外のアナリティクスプロバイダを使用してイベントを計測する場合、iOS SDKはデフォルトのセッション開始イベントとセッション終了イベントのみを送信することがありますが、これにはこのプロパティは含まれません。

ローカルテストの場合、セッションリプレイが機能することを確認するために、セッション開始イベントを強制できます。

1. Amplitude のユーザー検索イベントストリームに、[Amplitude] Session Replay ID プロパティを含むセッション開始イベントが表示されるはずです。処理が完了すると、そのセッションに対して「セッションを再生」ボタンが表示されます。

サンプリング

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

一部のセッションには、セッションリプレイ ID プロパティが含まれていません。

セッションリプレイでは、セッション内のすべてのイベントに [Amplitude] Session Replay ID プロパティが含まれている必要はなく、セッション内の少なくとも1つのイベントにそのプロパティが含まれていれば十分です。理由 [Amplitude] Session Replay IDイベントに含まれていない可能性があるものは、次のとおりです。

• ユーザーがオプトアウトしているか、現在の sampleRate ではそのセッションがサンプリング対象に含まれていない可能性があります。を増やす sampleRateより多くのセッションがキャプチャされます。
• Amplitude のイベントは引き続きプロバイダー経由で送信される場合がありますが、additionalEventProperties返しません [Amplitude] Session Replay ID プロパティ。これは、optOutおよびsampleRateの設定が原因で発生する可能性があります。optOut と sampleRate がそのセッションを含むように設定されていることを確認してください。

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

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

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

問題を報告する

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

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

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