Session Replay Standalone SDK

セッションリプレイ スタンドアロン SDK は、Amplitude Browser SDK とは独立してセッション録画をサイトに追加します。製品内分析にAmplitude以外のプロバイダーを使用している場合は、このオプションを選択してください。 サイトで既に Amplitude Browser SDK を使用している場合は、セッションリプレイ Browser SDK プラグインを使用してください。

バンドルサイズ

セッションリプレイのスタンドアロンSDKは、アプリケーションのバンドルサイズを増加させます。

現在のバンドルサイズに関する情報は、npm パッケージページまたは BundlePhobia を確認してください。

ランタイムパフォーマンス

セッションリプレイは非同期に実行され、メインスレッドをブロックしないようにバックグラウンドでリプレイデータを処理します。パフォーマンス特性には次のものがあります：

• DOMキャプチャ: DOMスナップショットキャプチャによる処理時間の増加は、通常、ページインタラクションごとに5ミリ秒未満です。ページの複雑さに応じて、最初のページロードスナップショットキャプチャには10～50ミリ秒かかります。
• メモリ使用量: セッションリプレイはリプレイイベントをメモリまたは IndexedDB に保存します (storeType を使用して設定できます)。 メモリ使用量はセッション時間とページの複雑さによって変化します。通常、各アクティブなセッションについては1〜10MBの範囲です。
• CPU への影響：デフォルト設定では、セッションリプレイは通常動作時に CPU 時間の 2% 未満を使用します。 Amplitude は、performanceConfig.enabledがtrueに設定されている場合（デフォルト）、ブラウザのアイドル期間まで圧縮操作を延期します。
• ネットワーク帯域幅：Amplitude はアップロード前にリプレイデータを圧縮し、通常ペイロードサイズを 60 ～ 80% 削減します。 Amplitudeはネットワークリクエストをバッチ処理し、非同期に送信します。

パフォーマンスの最適化

セッションリプレイのパフォーマンスを最適化するには：

• useWebWorker を有効にすると、圧縮処理がメインスレッドから切り離され、メインスレッドへのCPUの影響が軽減されます。
• 遅延圧縮が発生するタイミングを制御するようにperformanceConfig.timeoutを構成します。
• sampleRate を使用してキャプチャされるセッションの数を減らすことで、CPU とメモリの使用量を直接削減できます。
• ページの再読み込み時に持続性を必要としない場合は、storeTypeをmemoryに設定します。これによりIndexedDBのオーバーヘッドが削減されます。

パフォーマンス テストの詳細な結果については、「セッションリプレイ パフォーマンス テスト」に関するブログ記事を参照してください。

セッションリプレイは、ページのドキュメントオブジェクトモデル (DOM) に対する変更（シャドウ DOM 内の要素など）をキャプチャし、これらの変更を再生してビデオのような再生を構築します。セッションの開始時に、セッションリプレイはページの DOM の完全なスナップショットをキャプチャします。ユーザーがページとやり取りする際、セッションリプレイは DOM への各変更を diff としてキャプチャします。セッションのリプレイを視聴するとき、セッションリプレイは各 diff を順番に元の DOM に適用し、リプレイを構築します。セッションリプレイには最大長はありません。

始める前に

セッションリプレイ Standalone SDK には次のことが必要です：

1. アプリケーションは Web ベースです。
2. 初期化時にセッション識別子を SDK に提供し、それが変更されたときに setSessionId を呼び出します。SDK はこの ID を使用してリプレイデータをバケットに格納します。 セッション ID の照合を行うには、アナリティクスイベントと SDK で同じセッション識別子を使用してください。 時間ベースのイベント照合のみの場合、セッションリプレイsessionIdは、フロントエンドで生成されたタイムバケット（たとえば、1時間単位でアラインされたミリ秒単位のUnixタイムスタンプ）であり、アナリティクスイベントには表示されません。
3. デバイスIDをSDKに提供できること。
4. スタンドアロンSDKに渡すDevice IDは、アナリティクスイベントのデバイスIDと一致している必要があります。

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

クイックスタート

プラグインを npm または yarn でインストールしてください。

# Install Session Replay SDK only
npm install @amplitude/session-replay-browser --save
# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified

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

1. リプレイの収集を開始するには、sessionReplay.initを呼び出してください。API キー、セッション識別子、デバイス識別子を渡します。
2. セッション識別子が変更された場合は、新しい値を sessionReplay.setSessionId を使用して Amplitude に渡します。
3. Amplitudeは自動的に[Amplitude] Replay Capturedイベントを作成して、リプレイとアナリティクスデータをリンクさせます。詳細については、『セッションリプレイID』を参照してください。

import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'
const AMPLITUDE_API_KEY = "key"
// Configure the SDK and begin collecting replays
await sessionReplay.init(AMPLITUDE_API_KEY, {
 deviceId: "<string>",
 sessionId: "<string | number>",
 optOut: "<boolean>",
 sampleRate: "<number>"
}).promise;
// Call whenever the session id changes
await sessionReplay.setSessionId(sessionId).promise;

また、スクリプトタグを使用してセッションリプレイを計測することもできます。

<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.51.6-min.js.gz"></script>
<script>
window.sessionReplay.init(AMPLITUDE_API_KEY, {
    deviceId: "<string>",
    sessionId: "<string | number>",
    sampleRate: "<number>"
    //...other options
})
// Call whenever the session id changes
window.sessionReplay.setSessionId(sessionId);
</script>

セッションリプレイID

Amplitudeは、セッションリプレイがセッションをキャプチャするときに[Amplitude] Replay Capturedイベントを自動的に作成します。このイベントには、リプレイをアナリティクスデータにリンクする[Amplitude] Session Replay IDプロパティが含まれています。 手動による計装は不要です。

[Amplitude] Session Replay ID はリプレイの一意の識別子であり、デフォルトでユーザーのセッションを識別する [Amplitude] Session ID とは異なります。

セッションリプレイ ID の形式は <deviceId>/<sessionId>です。セッションリプレイは区切り文字として/を使用するため、deviceIdとカスタムセッションID文字列値には/を含めることができません。使用できる文字：a-z A-Z 0-9 _ - . | @ : =。追加のキャラクターが必要な場合は、Amplitudeサポートまでお問い合わせください。

設定

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

APIエンドポイント

セッションリプレイは次のAPIエンドポイントを使用します。

• データの取り込み:
  • 米国: https://api-sr.amplitude.com/sessions/v2/track。
  • EU: https://api-sr.eu.amplitude.com/sessions/v2/track。
  • セッションリプレイは、キャプチャされたリプレイデータをこれらのエンドポイントに送信します。
• リモート設定:
  • 米国: https://sr-client-cfg.amplitude.com/config。
  • EU: https://sr-client-cfg.eu.amplitude.com/config。
  • セッションリプレイは、これらのエンドポイントからリモート設定を取得します。

ドメインプロキシを設定している場合は、これらのエンドポイントにリクエストを転送してください。trackServerUrlおよびconfigServerUrl設定オプションを使用して、これらのデフォルト値を上書きできます。

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

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

Light、Medium、Conservativeの各マスキングレベルとリモート設定による上書きは、セッションリプレイのプライバシー設定で設定します。リモート設定とSDK設定が競合する場合は、リモート設定が優先されます。

ブロックまたはマスクする要素は、設定時に privacyConfig オブジェクトで指定します。

// This configuration blocks .no-track and #ads, sets the default mask level,
// and defines the mask and unmask selectors.
await sessionReplay.init(AMPLITUDE_API_KEY, {
  privacyConfig: {
    blockSelector: ['.no-track', '#ads'],
    defaultMaskLevel: 'medium',
    maskSelector: ['.sensitive-data', '.user-email'],
    unmaskSelector: ['.public-info', '#main-content']
  }
}).promise;

CSSセレクター

セッションリプレイの設定では、さまざまな種類の CSSセレクターに対応しています。要素タグ（h1またはtextarea）、クラス名（.hidden）、またはデータ属性を指定します。

データ属性は、ハッシュ処理のためにクラス名が頻繁に変更される場合に役立ちます。 データ属性を使用するには、data-amp-unmaskやdata-amp-maskなどのカスタム属性を任意のHTML要素に追加します。 たとえば、<textarea data-amp-unmask></textarea> のようにし、セレクターとして指定する際は、属性を角括弧 [data-amp-unmask] で囲みます。

ユーザーのオプトアウト

セッションリプレイにはオプトアウト設定オプションがあります。初期化の一部として渡された場合、これによりAmplitudeはセッションリプレイを収集できません。 例えば：

// Pass a boolean value to indicate a users opt-out status
await sessionReplay.init(AMPLITUDE_API_KEY, {
  optOut: true,
}).promise;

コンテンツセキュリティポリシー（CSP）

Web アプリケーションが厳格なコンテンツセキュリティポリシーを使用している場合は、次のディレクティブを追加してください。

必要な CSP ディレクティブ

script-src: https://cdn.amplitude.com;
connect-src: https://api-secure.amplitude.com;
worker-src: blob:;

CSP ディレクティブのリファレンス

APIエンドポイント

セッションリプレイは次のエンドポイントにデータを送信します。

CSPヘッダーの例

米国のデータセンターの場合：

Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;

EUのデータセンターの場合：

Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;

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

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

// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
  serverZone: "EU",
}).promise;

サンプリングレート

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

// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01,
}).promise;

sampleRateを設定するには、セッションリプレイプランの月間割り当て量を考慮してください。 たとえば、月間割り当て量が 2,500,000 セッションで、月間平均セッション数が 3,000,000 の場合、割り当て量は平均セッション数の 83% です。 この場合、サンプリングが月全体にわたって継続されるようにするには、sampleRateを.83またはそれ以下に設定します。

サンプルレートを検討する際には、次の点に注意してください。

• 月間のセッションクォータに達すると、Amplitudeはリプレイ用のセッションのキャプチャを停止します。
• セッションクォータは毎月 1 日にリセットされます。
• 月の初めにクォータをフルに活用するのではなく、サンプルレートを使用して 1 か月間にセッションクォータを配布してください。
• 最適なサンプルレートを見つけられるように、Amplitudeでは低い値（例：.01）から始めることを推奨します。この値で十分なリプレイが記録されない場合は、数日のうちにレートを上げてください。 キャプチャされたセッションリプレイの数をモニターする方法については、「キャプチャされたセッション数の表示」を参照してください。

セッションリプレイはリモートサンプリングレート設定をサポートしています。これにより、組織内のユーザーはコードを変更することなく、実装後にプロジェクトのサンプリングレートを設定または更新できます。競合が発生した場合、セッションリプレイはデフォルトでリモートの設定になります。詳細については、アカウント設定を参照してください。

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

有効化されると、セッションリプレイは次のいずれかの状態になるまでサイト上で実行されます。

• ユーザーがサイトを離れる。
• sessionReplay.shutdown()呼び出します。

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

ユーザーがサイトの制限のないエリアに戻ったときに、sessionReplay.init(API_KEY, {...options}) を呼び出してリプレイ収集を再度有効にします。

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

import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'
const AMPLITUDE_API_KEY = <...>
await sessionReplay.init(AMPLITUDE_API_KEY, {
 deviceId: <string>,
 sessionId: <string | number>,
 optOut: <boolean>,
 sampleRate: <number>
}).promise;

データ保持

セッションリプレイは、プライバシーに関するリクエストや削除リクエストに対応するため、Amplitude のツールと API を使用します。レビュー 同意に関するガイダンスキャプチャを実装する際に。

データ保持期間

デフォルトのリテンション、延長リテンション、およびリテンション変更の有効日については、セッションリプレイのデータライフサイクルリファレンスをご覧ください。

DSAR API

Amplitude DSAR APIは、セッションのリプレイに関するメタデータを返しますが、生のリプレイデータは返しません。 Amplitudeは、セッションリプレイがセッションをキャプチャするときに[Amplitude] Replay Capturedイベントを自動的に作成します。このイベントには[Amplitude] Session Replay IDプロパティが含まれており、Amplitudeがユーザーのリプレイ用に収集したセッションに関する情報を提供します。

{
 "amplitude_id": 123456789,
 "app": 12345,
 "event_time": "2020-02-15 01:00:00.123456",
 "event_type": "first_event",
 "server_upload_time": "2020-02-18 01:00:00.234567",
 "device_id": "your device id",
 "user_properties": { ... },
 "event_properties": {
 "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
 },
 "session_id": 1699922971244,
}

データの削除

セッションリプレイはAmplitudeのユーザープライバシーAPIを使用して削除リクエストを処理します。削除要求が成功すると、指定されたユーザーのすべてのセッションリプレイが削除されます。

Session Replayを使用しているAmplitudeプロジェクトを削除すると、Amplitudeはそのリプレイデータを削除します。

ボットフィルター

セッションリプレイはAmplitudeアプリで使用できるのと同じブロックフィルターを使用します。 セッションリプレイは、イベントやユーザープロパティに基づいてトラフィックをブロックしません。

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

セッションリプレイは、ユーザーのブラウザにクッキーを設定しません。 代わりに、デフォルトで IndexedDB と呼ばれるブラウザーのストレージオプションに依存しています。 このオプションを使用すると、ユーザーがブラウザのタブを移動したり、タブを閉じた後再開したりするセッション中に継続的なリプレイ収集が可能になります。 SDK は IndexedDB に保存したデータを削除するため、ユーザーのディスク容量に影響を与えることはほとんどありません。

環境がIndexedDBに対応していない場合、セッションリプレイは代替手段としてメモリ内ストレージを使用します。インメモリストレージは耐久性が低く、ユーザーがブラウザウィンドウを閉じるとデータが失われます。 インメモリストレージを強制するには、設定オプションstoreTypeを'memory'に設定します。

ユーザーがサイト上のすべての Cookie を拒否した場合は、optOut 設定オプションを使用して、そのユーザーのリプレイデータ収集を無効にしてください。

IndexedDBのベストプラクティス

IndexedDBが初期化され、正しく動作していることを確認するには:

• CSPヘッダーを確認して、過度に制限的でないことを確認してください。default-src と script-src ディレクティブで必要なソースが許可されていることを確認してください。

• 同じオリジン内でIndexedDB操作を実行します。 クロスオリジン制限により、IndexedDB の操作がブロックされることがあります。

• ユーザーがIndexedDBをサポートする最新のブラウザーを使用していることを確認してください。Amplitudeは、Chrome、Firefox、Safari、Edge、またはOperaの最新バージョンを推奨しています。

既知の制限事項

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

• セッションリプレイは、複数のプロジェクトにわたって1人のユーザーからのリプレイを統合しません。 例えば：
  • マーケティングサイトとウェブアプリケーションを別々のAmplitudeプロジェクトとして計測し、それぞれでセッションリプレイを有効にすることができます。
  • 既知のユーザーがマーケティングサイトにアクセスし、Webアプリケーションにログインします。
  • Amplitudeは両方のセッションをキャプチャします。
  • 各セッションのリプレイはホストプロジェクトに表示されます。
• セッションリプレイは次のHTML要素をキャプチャできません：
  • キャンバス。
  • WebGL。
  • object Flash、Silverlight、Java などのプラグインを含むタグ。セッションリプレイはobject type="image"をサポートしています。
  • Lottie アニメーション。
  • crossOriginIframes.enabled: true を使用してセッションリプレイ SDK をロードしないクロスオリジン <iframe> 要素（Stripe や Google マップなどのサードパーティ製の埋め込みなど）。ファーストパーティ製のクロスオリジンiframeをキャプチャするには、クロスオリジンiframe録画に移動してください。
  • 認証を必要とするアセット（フォント、CSS、画像など）。
• セッションリプレイは広告ブロッキングソフトウェアと互換性がありません。

トラブルシューティング

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

CSSのスタイル設定がリプレイに表示されない

Amplitudeがリプレイをキャプチャする場合、アプリケーションやサイトの一部であるCSSファイルやその他の静的アセットをダウンロードして保存することはありません。セッションリプレイはこれらのファイルへの参照を保存し、リプレイを再構築する際にそれらの参照を使用します。状況によっては、以下の理由により、リプレイに表示されるスタイルがアプリケーションと異なる場合があります。

• サイト上のアセットが移動または名前が変更されました。 これは、アプリケーションの新しいバージョンをデプロイするときに発生することがあります。
• サイト上のアセットはアクセス制御の背後にあり、Amplitudeがそれらを取得できないようにしています。

CSS読み込みに関する問題を解決するには:

• ドメインが一般公開されていることを確認してください。 アセットを localhost に保存している場合は、それらをステージング環境に移動してみてください。
• CDNは古いリプレイ用に古いスタイルシートを記録しておく必要があります。同じスタイルシートのコンテンツが時間の経過とともに変化する場合は、アセットのURLに固有の文字列またはハッシュを追加してみてください。例：stylesheet.css?93f8b89。
• サーバーの CORS 設定で許可されているドメインのリストに app.amplitude.com または app.eu.amplitude.com を追加します。

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

状況によっては、リプレイの長さが[Amplitude] Start Sessionイベントと[Amplitude] End Sessionイベントの間の時間を超えることがあります。これは、ユーザーがブラウザまたはブラウザのタブを閉じたときに発生し、[Amplitude] End Session 発生していますが、Browser SDK とセッションリプレイプラグインはまだそのイベントを処理していません。ユーザーが再びそのページにアクセスすると、SDK とプラグインがイベントを処理し、リプレイと一緒にそれを Amplitude に送信します。 End Session Client Event TimeとClient Upload Timeの間に不一致がある場合、この状況が発生していることを確認できます。

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

• コンテンツセキュリティポリシー
• ブロックされたJavaScript
• 現在のセッションでブラウザSDKを介してトリガーされたイベントはありません。
• サンプリング

ローカル開発とフォーカス状態

セッションリプレイ SDK とプラグインは、フォーカスされているページのみをキャプチャします。 ブラウザコンソールを開いた状態でローカルで開発する場合、フォーカスの状態が期待どおりに動作しないことがあります。Amplitudeでリプレイが表示されない場合は、debugModeを有効にしてください。 このモードでは、セッションリプレイはフォーカスハンドルを無視し、追加のデバッグ情報を有効にします。

const sessionReplayTracking = window.sessionReplay.plugin({
 debugMode: true,  
 sampleRate: 1,
 });

コンテンツセキュリティポリシー

サイトにセッションリプレイスクリプトを追加する際は、セッションリプレイ SDKが実行されているページにアクセスし、ブラウザの開発者ツールを開きます。

JavaScript コンソールで、テキストContent Security Policyを含むエラーメッセージがないかを確認してください。 たとえば、Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy。

このエラーを解決するには、サイトのコンテンツセキュリティポリシーを更新して、AmplitudeのAPIへの接続を許可してください。

ブロックされたJavaScript

ブラウザ拡張機能やネットワークセキュリティポリシーは、セッションリプレイSDKをブロックしている可能性があります。 ブラウザの開発者ツールでリクエストが失敗していないか確認し、失敗している場合はブロックされたドメインに例外を追加してください。

サンプリング

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

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

セッションリプレイでは、セッション内のすべてのイベントにその [Amplitude] Session Replay ID プロパティが含まれている必要はなく、セッション内の1つのイベントにのみこのプロパティが含まれていれば十分です。セッションリプレイに接続しているソースとは異なるソースでイベントを計測すると、このプロパティが存在しない場合があります。たとえば、アプリケーションがブラウザSDKではなくバックエンドソースからイベントを送信する場合があります。

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

一般的に、再生は取り込まれてから数分以内に表示されます。 遅延やエラーは、次のいずれかまたは複数の原因によって発生することがあります。

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