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

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

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

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

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

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

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

問題の報告

iOS用セッションリプレイに関する問題を報告される場合は、AmplitudeSessionReplay-ios GitHubリポジトリにアクセスしてください。

始める前に

セッションリプレイ 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 13です。

クイックスタート

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

Package.swiftファイルまたはXcodeのPackageリストの依存関係として、セッションリプレイを追加します。

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

サードパーティのアナリティクスと統合するには、AmplitudeSessionReplayターゲットを使用します。

swift
.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を使用してセッションリプレイのプロパティを収集し、他のイベントプロパティと一緒に送信します。
swift
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を設定し、カスタムセッションが変更される度に更新します。

swift
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設定します。

swift
sessionReplay.privacyConfig = PrivacyConfig(maskLevel: .conservative)

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

リモート設定

リモート設定を有効にすると、Amplitudeでサンプルレートとマスングレベルを設定できます。

リモート設定とテスト

enableRemoteConfigをtrueに設定すると、Amplitudeで定義した設定が、SDKでローカルに定義した設定よりも優先されます。そのため、アプリケーションのテスト中は、リモート設定を無効にして、sampleRateを1に設定し、テストセッションを確実にキャプチャできるようにする必要があります。

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

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

マスクレベル

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

セッションリプレイの設定にある、このオプションを使用します。

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

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

swift
import AmplitudeSessionReplay

SwiftUIのプライバシー修飾子

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

swift
import AmplitudeSessionReplay

ユーザーのオプトアウト

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

swift
// 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に設定します。 例えば:

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

サンプリングレート

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

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

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

ターゲットを絞ったリプレイキャプチャ

セッションリプレイiOSスタンドアロンSDK 0.15.0以降は、Targeted Replay Capture(TRC)をサポートしています。これは、セッションリプレイ設定で設定した条件に一致するセッションのみをキャプチャします。スタンドアロンSDKは分析イベントを受信しないため、イベントとユーザーのプロパティをセッションリプレイに渡します:

  • SessionReplayインスタンスを作成した直後にユーザーのプロパティの完全なセットでevaluateTargeting(userProperties:)を呼び出し、プロパティが変更されるたびに再度呼び出してください。各呼び出しは、前の呼び出しのプロパティを置き換えます。
  • イベントにadditionalEventPropertiesを追加する前に、各イベントに対してevaluateTargeting(eventType:eventProperties:)を呼び出します。この順序により、セッションリプレイは条件に一致するイベントにタグを付けます。
swift
// Right after you create the instance, and whenever the user's properties change
sessionReplay.evaluateTargeting(userProperties: ["plan": "Pro"])
// For each event, before you add the Session Replay properties
sessionReplay.evaluateTargeting(eventType: event.eventType,
                                eventProperties: event.eventProperties)
var eventProperties = event.eventProperties ?? [:]
eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current }
event.eventProperties = eventProperties
ThirdPartyAnalytics.track(event)

イベント、イベントプロパティ、ユーザープロパティの各条件はiOSに適用されます。ページURLの各条件は適用されません。

録画品質

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

swift
// 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 */)

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

swift
sessionReplay.quality = .medium

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

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

swift
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()を呼び出します。 これは、ホストアナリティクスクライアントがフラッシュされるときに、同時にセッションリプレイをフラッシュしたい場合に便利です。

swift
sessionReplay.flush()

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

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

ウェブビューのサポート(ベータ版)

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

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

swift
// UIKit
webView.amp_isBlocked = false

マップビューに対するサポート(アルファ版)

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

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

ログ記録

可用性

AmplitudeSessionReplay 0.8.0以降はログ記録をサポートしています。

セッションリプレイは、iOSアプリケーションでのログ記録をサポートしています。連携を初期化するときにrecordLogOptionsで制限を設定し、その後recordLog(level:message:date:)を通じてログメッセージを送信します。

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

ログシステムを実装している場合は、単一ポイントに変更を加えるだけでログ記録の機能を統合することができます。詳細については、次の例を参照してください。

CocoaLumberjack

CocoaLumberjackを使用している場合、カスタムロガープロバイダーと統合できます。

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

React Native

consoleログまたはconsoleTransportを指定したreact-native-logsを使用している場合は、RCTAddLogFunctionと統合できます。

swift
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)
}

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

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

リテンション期間

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

DSAR API

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

データの削除

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

ボットフィルター

ボットによるフィルタリングとプロパティフィルタの制限については、セッションリプレイのボットフィルタリングを参照してください。

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

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

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

既知の制限事項

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

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

    • 複数のアプリを個別のAmplitudeプロジェクトとしてインストルメントし、各プロジェクトでセッションリプレイを有効にします。
    • 既知のユーザーが1つのアプリの利用を開始し、その後別のアプリに切り替えます。
    • 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はデフォルトのSession StartイベントとSession Endイベントのみを送信することがあります。このイベントには、このプロパティが含まれません。

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

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

サンプリング

前述したように、セッションリプレイのsampleRateのデフォルト値は0です。レートをより高い数値に更新してください。 詳細については、サンプリングレートを参照してください。

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

セッションリプレイでは、セッション内のすべてのイベントに[Amplitude] Session Replay IDプロパティがある必要はなく、セッション内の1つのイベントに含まれていれば動作します。イベントに[Amplitude] Session Replay IDが存在しない理由としては、次のようなものがあります。

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

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

一般的に、再生は取り込んでから数分以内に利用可能になるはずです。遅延やエラーは、次のいずれかまたは複数の原因によって発生する可能性があります:

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

問題をレポート

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

問題を作成する際は、以下を含めてください:

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

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

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.

このページでは