セッションリプレイ iOS ミドルウェア
早期アクセスSDK
アルファ版リリースであるため、このSDKにはバグが含まれていたり、クラッシュが発生したりする可能性があります。本番環境で有効にする前に、管理された環境でアプリを十分にテストしてください。開発者向けプレビューSDKのベストプラクティスについての詳細は、SDKのメンテナンスとサポートを参照してください。
この記事では、iOS SDKミドルウェアを使用したセッションリプレイのインストールについて説明します。アプリがすでに(メンテナンス用の)Amplitude SDKを使用している場合は、このオプションを使用してください。
アプリがすでに(最新)iOS Swift SDKを使用している場合は、セッションリプレイiOS SDKプラグインを選択してください。
Analytics-Swift SDKとAmplitude(アクション)の送信先経由でセグメントを使用する場合は、セグメントプラグインを選択してください。
製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。
セッションリプレイとパフォーマンス
Amplitudeでは、インストール先のiOSアプリのパフォーマンスへの影響を最小限に抑えるためにセッションリプレイを構築しました。
- メインユーザーインターフェースのスレッドをブロックしないように、リプレイデータを非同期に処理します。メインスレッドを使用してビュー階層を操作する必要がありますが、すべての処理はバックグラウンドキューで実行されます。
- バッチ処理と軽量圧縮を使用して、ネットワーク接続数と帯域幅を削減します。
- ビュー階層の処理を最適化します。階層の処理に問題が発生した場合は、Amplitudeにお問い合わせください。
始める前に
セッションリプレイミドルウェアには以下が必要です。
- アプリケーションは iOS または iPadOS 上で実行されます。
- (メンテナンス)Amplitude iOS SDKの
8.22.0以上を使用していること。 - デバイスIDをSDKに提供できること。
サポートされているiOSバージョン
セッションリプレイがサポートする最小のターゲットバージョンはiOS 13です。
クイックスタート
プロジェクトの依存関係に最新バージョンのミドルウェアを追加してください。
Package.swiftファイルの依存関係として、またはXcodeのPackageリストにセッションリプレイを追加します。
dependencies: [
.package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.20.0")
]
Amplitude-iOSと統合する場合は、AmplitudeiOSSessionReplayMiddlewareターゲットを使用してください。
.product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay")
アプリケーションコードを設定します。
import Amplitude
import AmplitudeiOSSessionReplayMiddleware
// Initialize Amplitude Analytics SDK instance
let amplitude = Amplitude.instance()
// Although not required, we recommend enabling session start and end events when enabling Session Replay
amplitude.defaultTracking.sessions = true
// Create and Install Session Replay Middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1))
amplitude.initializeApiKey(API_KEY)
設定
セッションリプレイミドルウェアを初期化する際には、次のオプションを渡します。
| オプション | タイプ | 必須 | デフォルト | 概要 |
|---|---|---|---|---|
sampleRate | Float | いいえ | 0 | リプレイ収集のために選択するセッションの数を制御します。 0から1の間の小数(例:0.4)を使用します。これは、セッションのリプレイ収集用にランダムに選択されるセッションの割合を表します。セッションが多数ある場合、0.4ではそれらのセッションのうちの40%を選択します。詳細については、サンプリングレートを参照してください。 |
enableRemoteConfig | Bool | いいえ | true | このセッションリプレイのインスタンスに対するリモートコンフィギュレーションを有効または無効にします。 |
autoStart | Bool | いいえ | true | セッションリプレイの初期化時に、自動的にキャプチャを開始するかどうかを制御します。 |
maskLevel | MaskLevel | いいえ | .medium | セッションリプレイで画面上のコンテンツをマスクする量を設定します。 .light、.medium、または.conservativeを使用します。詳細については、マスクレベルを参照してください。 |
captureWebViews | Bool | いいえ | false | ウェブビューコンテンツのキャプチャを有効にします。デフォルトでは、セッションリプレイはウェブビューをブロックします。 |
webviewMappings | [String: String] | いいえ | [:] | キャプチャされたWebビューコンテンツ内のサブストリングを置換値にマッピングします。captureWebViewsを有効にすると、セッションリプレイはアップロード前に、ウェブビューの記録データに対して、各エントリを大文字と小文字を区別しない検索と置換として適用します。これは高度なオプションです。ほとんどのアプリでは空のままにします。 |
recordLogOptions.logCountThreshold | Int | いいえ | 1000 | セッションごとのログの最大数を設定します。 |
recordLogOptions.maxMessageLength | Int | いいえ | 2000 | ログメッセージの最大長を設定します。 |
quality | QualityProfile | いいえ | .high | キャプチャとエンコードの品質を制御します(フレームレートや画像解像度など)。 .low、.medium、または.highを使用して、再生の忠実度とパフォーマンスおよびストレージのバランスを調整します。SDKがデバイスに基づいてプロファイルを選択できるようにする場合は、QualityProfile.automaticを使用します。 |
uploadConfig | UploadConfig | いいえ | UploadConfig() | セッションリプレイがデータをアップロードするタイミングと場所を制御します。従量課金制ネットワーク(携帯電話など)でのアップロードを一時停止するには、UploadConfig(disableMeteredUploads: true)を使用します。UploadConfig(serverUrl:)を使用して、プロキシにアップロードを送信します(バージョン0.14.0以降)。 |
画面上のデータをブロックする
セッションリプレイは、機密性の高い画面上のデータをブロックする3通りの方法をサポートしています。WebViewsのマスキング設定は、ウェブビューのサポートセクションにあります。
マスクレベル
iOS向けセッションリプレイは、maskLevelオプションで設定可能な3つのレベルのマスキングをサポートしています。
セッションリプレイの設定にある、このオプションを使用します。
| マスクレベル | 概要 |
|---|---|
light | すべてのパスワード、メールアドレス、クレジットカード番号、電話番号をマスクします。 |
medium | すべての編集可能なテキストビューをマスクします。 |
conservative | すべてのテキストビューをマスクします。 |
UIKitのプライバシーメソッド
セッションリプレイは、プライバシーを管理するためのUIView拡張機能を提供します。この機能にアクセスするには、セッションリプレイライブラリをインポートします。
import AmplitudeSessionReplay
| 変数 | 概要 |
|---|---|
amp_isBlocked | セッションリプレイでビューとそのサブビューを選択してプレースホルダに置き換えるには、view.amp_isBlockedを設定します。UITextViewsとUITextFieldsが自動的にブロックされます。デフォルトでマスクされているビューのブロックを解除するには、この値をfalseに設定します。 |
SwiftUIのプライバシー修飾子
セッションリプレイは、プライバシーを管理するためのView拡張機能を提供します。セッションリプレイライブラリをインポートしてアクセスします。
import AmplitudeSessionReplay
| 修飾子 | 概要 |
|---|---|
amp_setBlocked(_ blocked: Bool) | セッションリプレイでビューとそのサブビューを選択してプレースホルダに置き換えるには、amp_setBlocked()修飾子をViewに追加します。デフォルトでマスクされているビューのブロックを解除するには、この値をfalseに設定します。 |
ユーザーのオプトアウト
セッションリプレイミドルウェアはAmplitude-iOS SDKのoptOut設定に従っており、単独ではユーザーのオプトアウトをサポートしていません。
// Set optOut on the Amplitude SDK
amplitude.optOut = true
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
EU域内のデータレジデンシー
セッションリプレイは、EUデータセンターを使用するAmplitudeのお客様が利用できます。初期化時にserverZone設定オプションを EUに設定します。 例えば:
// Set serverZone on the Amplitude SDK
amplitude.setServerZone(.EU)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
サンプリングレート
デフォルトでは、セッションリプレイはリプレイ用にセッションの0%をキャプチャします。SDKのsampleRate設定オプションを使用して、キャプチャするセッションの割合を設定します。
手動サンプリングおよび動的サンプリング、クォータの計画、クォータの集計については、セッションリプレイのサンプリングを設定するを参照してください。
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.01))
録画品質
再生の忠実度と、パフォーマンスおよびストレージのバランスを調整するには、品質プロファイルを選択します。プロファイルが小さいほど、キャプチャフレームレートが低くなり、画像解像度も低くなります。プロファイルが高いほど、フレームレートと解像度が高くなります。SDKがデバイスに基づいてプロファイルを選択できるようにする場合は、QualityProfile.automaticを使用します(例:新しいデバイスでは高く、古いデバイスでは低くするなど)。
// Use automatic profile selection based on device
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
sampleRate: 0.1,
quality: .automatic
))
// Or set a fixed profile (low, medium, or high)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
sampleRate: 0.1,
quality: .medium
))
従量課金制ネットワークでのアップロードを無効にする
デバイスが従量課金制ネットワークに接続されている間は、セッションリプレイのアップロードを一時停止し、ユーザーのモバイルデータの使用を避けてください。セッションリプレイは引き続きデータをローカルに記録します。デバイスがWi-Fi、またはその他の従量制ではない接続に再接続されると、アップロードが再開されます。
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
sampleRate: 0.1,
uploadConfig: UploadConfig(disableMeteredUploads: true)
))
リプレイ収集を無効にする
有効化された後、セッションリプレイは次のいずれかまでアプリ上で実行されます:
- ユーザーがアプリを離れる。
sessionReplayMiddleware.stop()呼び出します。- このミドルウェアは
amplitude.removeEventMiddleware(sessionReplayMiddleware)を使用することでSDKから削除できます。
ユーザーがアプリの制限付きエリアに移動する前にsessionReplayMiddleware.stop()を呼び出して、ユーザーがそのエリアにいる間のリプレイ収集を無効にします。
参照の保持
これには、セッションリプレイ ミドルウェアインスタンス let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(/* session replay options */)への参照を保持する必要があります。
ユーザーがアプリの制限のないエリアに戻ったときに、sessionReplayMiddleware.start()を呼び出してリプレイ収集を再度有効にします。
特定の画面のみをキャプチャするには、起動時にミドルウェアが起動しないようにautoStart: falseでミドルウェアを初期化し、ユーザーがこれらの画面に出入りする際にstart()とstop()を呼び出します。
// Add the middleware once, without starting capture
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(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 実験などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にするロジックを作成することもできます。たとえば、特定のユーザーグループを対象とするフィーチャーフラグを作成し、それを初期化ロジックに追加できます。
import Amplitude
import AmplitudeiOSSessionReplayMiddleware
// Your existing initialization logic with Amplitude-iOS SDK
let amplitude = Amplitude.instance()
if (nonEUCountryFlagEnabled) {
// Create and Install Session Replay Middleware
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1)
amplitude.addEventMiddleware(sessionReplayMiddleware)
}
amplitude.initializeApiKey(API_KEY)
ウェブビューのサポート(ベータ版)
デフォルトでは、セッションリプレイはキャプチャ内のウェブビューをブロックします。すべてのWebViewコンポーネントのキャプチャを有効にするには、セッションリプレイ設定でcaptureWebViewsをtrueに設定します。
特定のWebViewコンポーネントをマスクするには、画面上のデータをブロックするに記載されているプライバシーメソッドを使用します。
// UIKit
webView.amp_isBlocked = false
マップビューに対するサポート(アルファ版)
セッションリプレイは、iOSアプリケーションでのマップビューのキャプチャをサポートしています。マップビューのキャプチャを有効にするには、実装でマップビューのマスクを解除します。
// 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を使用している場合、カスタムロガープロバイダーと統合できます。
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と統合できます。
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.