セッションリプレイ iOS プラグイン

この記事では、iOS プラグインを使用して セッションリプレイ をインストールする方法について説明します。 アプリがすでにAmplitude iOS Swift SDKまたはレガシーAmplitude iOS SDKを使用している場合は、このオプションを使用してください。

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

製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。

Unified SDK

Unified SDK for Swiftをインストールすることで、他のAmplitude製品(アナリティクス、実験)とともにセッションリプレイにアクセスできます。Unified SDKは、Amplitudeのすべての機能に単一のエントリーポイントを提供し、すべてのコンポーネントの初期化と設定を処理することで統合を簡素化します。

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

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

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

セッションリプレイは、メインビューとそのすべての子ビューを含む、アプリケーションのビューツリーへの変更を再帰的にキャプチャします。その後、 セッションリプレイ はこれらの変更を再生して、ビデオのような再生を構築します。セッションの開始時に、 セッションリプレイ はアプリケーションのビューツリーの完全なスナップショットをキャプチャします。ユーザーがアプリとやり取りするときに、セッションリプレイはビューの変更をそれぞれdiffとしてキャプチャします。セッションのリプレイを視聴するとき、セッションリプレイは各差分を順番に元のビューツリーに適用し、リプレイを構築します。セッションリプレイには最大長はありません。

問題の報告

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

始める前に

使用する方法は、使用しているAmplitude iOS SDKのバージョンによって異なります。

セッションリプレイiOSプラグインには以下が必要です。

  1. アプリケーションは iOS または iPadOS 上で実行されます。
  2. iOS Swift SDKの1.9.0以降を使用していること。

サポートされているiOSバージョン

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

クイックスタート

プラグインの最新バージョンをプロジェクトの依存関係に追加します。

Swift Package Manager

セッションリプレイをPackage.swiftファイルの依存関係として追加するか、Xcodeのパッケージリストに含めます。

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

Amplitude-Swiftと統合する場合は、AmplitudeSwiftSessionReplayPluginターゲットを使用してください。

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

CocoaPods

コアライブラリとプラグインをPodfileに追加してください。

plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.19.0'
pod 'AmplitudeSwiftSessionReplayPlugin', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.19.0'

アプリケーションコードを設定する

swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin
// Initialize Amplitude Analytics SDK instance
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY))
// Create and Install Session Replay Plugin
// Recording will be handled automatically
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0))

設定

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

カスタムセッションID

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

customSessionIdを設定した場合、この値がプラグインがAmplitude SDKから同期するセッションIDよりも優先されます。AmplitudeセッションIDの使用を再開するには、プロパティをnilに設定します。

swift
// Keep a reference to the plugin to set the custom session ID
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0)
sessionReplayPlugin.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
amplitude.add(plugin: sessionReplayPlugin)
// Whenever your custom session changes
sessionReplayPlugin.customSessionId = NEW_CUSTOM_SESSION_ID

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

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

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

アプリの実行中に自動マスキングレベルを変更するには、プラグインprivacyConfigに設定してください。プラグインをAmplitudeに追加する前または後に設定してください。

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

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

リモート設定

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

リモート設定とテスト

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

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

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

マスクレベル

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

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

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

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

swift
import AmplitudeSessionReplay

SwiftUIのプライバシー修飾子

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

swift
import AmplitudeSessionReplay

ユーザーのオプトアウト

セッションリプレイプラグインはAmplitude-Swift SDKのoptOut設定に従っており、単独ではユーザーによるオプトアウトをサポートしていません。

swift
// Set optOut on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           optOut: true,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))

EU域内のデータレジデンシー

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

swift
// Set serverZone on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           serverZone: .EU,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))

サンプリングレート

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

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

swift
// This configuration samples 1% of all sessions
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.01))

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

セッションリプレイiOSプラグイン0.15.0以降は、Targeted Replay Capture(TRC)をサポートしています。これは、セッションリプレイ設定で設定した条件に一致するセッションのみをキャプチャします。プラグインは、iOS Swift SDKからの各イベントとユーザーのプロパティに対してこれらの条件を評価するため、TRCには追加のコードは必要ありません。 イベント、イベントプロパティ、ユーザープロパティの条件はiOSに適用されますが、ページURLの条件は適用されません。

録画品質

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

swift
// Use automatic profile selection based on device
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .automatic
))
// Or set a fixed profile (low, medium, or high)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .medium
))

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

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

swift
// Set uploadConfig through the plugin's Config initializer
let config = AmplitudeSwiftSessionReplayPlugin.Config(
    sampleRate: 0.1,
    uploadConfig: UploadConfig(disableMeteredUploads: true)
)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(config: config))

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

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

  • ユーザーがアプリを離れる。
  • sessionReplayPlugin.stop()呼び出します。
  • このプラグインはamplitude.remove(plugin: sessionReplayPlugin)を使用してSDKから削除できます。

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

参照の保持

これには、SessionReplayPluginインスタンスlet sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(/* session replay options */)への参照を保持する必要があります。

ユーザーがアプリの制限のないエリアに戻ったときに、sessionReplayPlugin.start()を呼び出してリプレイ収集を再度有効にします。

特定の画面のみをキャプチャするには、起動時に起動しないようにautoStart: falseでプラグインを初期化し、ユーザーがこれらの画面に出入りするときに、start()およびstop()を呼び出します。

swift
// Add the plugin once, without starting capture
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0, autoStart: false)
amplitude.add(plugin: sessionReplayPlugin)
// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()
// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()

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

swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin
// Your existing initialization logic with Amplitude-Swift SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY,
                                                           /* other configuration */))
if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.1)
  amplitude.add(plugin: sessionReplayPlugin)
}

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

デフォルトでは、セッションリプレイはキャプチャ内のウェブビューをブロックします。すべての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をバッキングレイヤーとするビュー

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

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.

このページでは