セッションリプレイ Browser SDKプラグイン
セッションリプレイの計測
セッションリプレイはデフォルトではオンになっていません。標準のAmplitude計測以上の設定が必要です。
セッションリプレイ Browser SDK プラグインは、Amplitude Browser SDK 2 で既に計測されているサイトにセッション録画を追加します。サイトが既にAmplitude計測を使用している場合は、このオプションを使用してください。製品内アナリティクスにAmplitude以外のプロバイダーを使用している場合は、スタンドアロンの実装を選択してください。ブラウザ SDK の詳細については、ブラウザ SDK 2 を参照してください。
セッションリプレイとパフォーマンス
セッションリプレイは、インストール先のWebページのパフォーマンスへの影響を次のように最小限に抑えます。
- Webhookを通じてコンテンツを非同期に処理することで、効率的な圧縮と最適化されたバンドルサイズを実現できます。
- リクエストをバッチ処理し、軽量圧縮を使用してネットワーク接続と帯域幅を削減します。
- DOM処理の最適化。
バンドルサイズ
セッションリプレイプラグインは、アプリケーションのバンドルサイズを増やします。
現在のバンドルサイズに関する情報は、npm パッケージページまたは BundlePhobia を確認してください。
ランタイムパフォーマンス
セッションリプレイは非同期に実行され、メインスレッドをブロックしないようにバックグラウンドでリプレイデータを処理します。パフォーマンス特性には次のものがあります:
- DOMキャプチャ: DOMスナップショットキャプチャによる処理時間の増加は、通常、ページインタラクションごとに5ミリ秒未満です。ページの複雑さによっては、初期ページロードスナップショットキャプチャには10〜50ミリ秒かかることがあります。
- メモリ使用量: セッションリプレイはリプレイイベントをメモリまたは IndexedDB に保存します (
storeTypeを使用して設定できます)。 メモリ使用量はセッション時間とページの複雑さによって変化します。通常、各アクティブなセッションについては1〜10MBの範囲です。 - CPU への影響:デフォルト設定では、セッションリプレイは通常動作時に CPU 時間の 2% 未満を使用します。 セッションリプレイは、
performanceConfig.enabledがtrue(デフォルト)の場合、圧縮操作をブラウザのアイドル期間まで延期します。 - ネットワーク帯域幅: セッションリプレイはアップロード前にリプレイデータを圧縮するため、通常ペイロードサイズを 60 ~ 80% 削減できます。セッションリプレイはネットワーク要求をバッチ処理し、非同期に送信します。
パフォーマンスの最適化
セッションリプレイのパフォーマンスを最適化するには:
useWebWorkerを有効にすると、圧縮がメインスレッドから外れ、CPU への影響が軽減されます。- 遅延圧縮が発生するタイミングを制御するように
performanceConfig.timeoutを構成します。 - ページを再読み込みしたときに持続性を維持する必要がない場合は、
storeTypeをmemoryに設定してください。これにより IndexedDB のオーバーヘッドが削減されます。
パフォーマンステストの詳細な結果については、セッションリプレイのパフォーマンステストに関するブログ記事を参照してください。
セッションリプレイは、ページのドキュメントオブジェクトモデル(DOM)への変更をキャプチャします(シャドウDOM内の要素も含まれます)。その後、 セッションリプレイ はこれらの変更を再生して、ビデオのような再生を構築します。例えば、セッションの開始時に、セッションリプレイはページのDOMの完全なスナップショットをキャプチャします。ユーザーがページとやり取りする際、セッションリプレイは DOM への各変更を diff としてキャプチャします。セッションのリプレイを視聴するとき、セッションリプレイは各 diff を順番に元の DOM に適用し、リプレイを構築します。セッションリプレイには最大長はありません。
サーバー側のレンダリングとハイドレーション
Next.js、Nuxt、SvelteKit、Angular SSR、React Routerなどのフレームワークは、サーバー上でHTMLをレンダリングし、ブラウザでハイドレートします。 Recorderは、ドキュメントの解析が完了するまで待ち、その後、サーバーでレンダリングされたHTMLの完全なスナップショットを取得します。セッションリプレイは、ハイドレーション期間中にフレームワークが加えたすべての DOM 変更を増分変更として記録します。そのため、このリプレイはユーザーが各時点で見た内容を示します。
セッションリプレイはブラウザでのみ実行されます。プラグインを追加し、クライアント専用コード(クライアントエントリファイル、useEffectフック、onMountコールバックなど)でinitを呼び出します。サーバーでも実行されるコードでは呼び出さないでください。
SDKの初期化を延期する
セッションリプレイの初期化をページ読み込み後まで延期すると、ページ読み込みメトリックに対するSDKの影響を排除できます。このアプローチは、Time to InteractiveやLargest Contentful Paintなどのロードタイムのメトリクスを測定し、セッションリプレイのインパクトをゼロにする必要がある場合に使用します。 初期化を早めに保ちながら影響を減らすことが目標の場合は、代わりにパフォーマンス最適化の設定オプションを使用してください。
Amplitudeを通常どおり初期化し、loadイベントリスナーを使用してセッションリプレイプラグインのみを遅延させます:
import * as amplitude from "@amplitude/analytics-browser";
// Initialize Amplitude at page load as usual
amplitude.init(API_KEY);
// Load and add the Session Replay plugin only after the page has fully loaded
window.addEventListener('load', async () => {
const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
await amplitude.add(sessionReplayTracking).promise;
});
または、requestIdleCallbackを使用してブラウザがアイドル状態になるまで延期します。このアプローチは、アクティビティの少ない瞬間を待機し、他のポストロードワークとの競合を減らします。
import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(API_KEY);
requestIdleCallback(async () => {
const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
await amplitude.add(sessionReplayTracking).promise;
});
セッションリプレイは、初期化時に完全なDOMスナップショットをキャプチャします。 初期化前に発生したインタラクションは、リプレイには表示されません。
Angularアプリ
Zone.jsを使用しているAngularアプリで、Browser SDK 2 Angularのガイダンスに記載されている方法と同じように、プラグインを追加し、Angularゾーンの外側でinitを呼び出します。 たとえば、main.ts の前に bootstrapApplication で両方を呼び出します:
// main.ts
import { bootstrapApplication } from "@angular/platform-browser";
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";
amplitude.add(sessionReplayPlugin({ sampleRate: 1 }));
amplitude.init(AMPLITUDE_API_KEY);
bootstrapApplication(AppComponent, appConfig);
Recorderはすでにブラウザの未適用済みのMutationObserverを使用しているため、DOMミューテーションの追跡はZone.js経由で実行されません。Recorderのイベントリスナー(マウス、スクロール、入力リスナーなど)は、Zone.jsを通じて実行されます。RecorderがAngularゾーン内で開始されている場合、記録された各イベントはAngular変更検出をトリガーします。
前提条件
セッションリプレイプラグインには次のことが必要です。
- アプリケーションは Web ベースです。
- デバイスIDをSDKに提供できること。
- このサイトでは、ブラウザ2.0 SDKを使用しています。
サポートされているブラウザー
セッションリプレイはAmplitudeのSDKと同じブラウザセットをサポートしています。詳細については、「ブラウザーの互換性」を参照してください。
セッションリプレイは、ブラウザ拡張機能やブラウザ拡張機能が導入するDOM要素すべてをサポートしているわけではない場合があります。
セッションリプレイはShadow DOMをサポートしていますが、サイトで使用しているフレームワークによっては例外が存在する場合があります。
クイックスタート
プラグインを npm または yarn でインストールしてください。
Amplitudeは初めてですか? Unified SDKを使用してください。
Browser SDKをまだインストールしていない場合は、Browser Unified SDK (@amplitude/unified) を使用してください。これには、分析と実験と並んで、セッションリプレイが単一のパッケージに含まれています。両方をインストールするのではなく、1つのパッケージのエントリポイントを選択します。
# New integration: install the Unified SDK (includes Session Replay)
npm install @amplitude/unified
# Existing Browser SDK integration: add the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save
アプリケーションコードを設定します。
import { initAll } from "@amplitude/unified";
// Initialize Unified SDK with Session Replay enabled
initAll("YOUR_API_KEY", {
sessionReplay: {
sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
},
});
また、コードをサイトの<head>に直接追加することもできます。この方法を使用すると、アプリケーションが他の場所でBrowser SDKを初期化しないようにしてください。ブラウザSDKを複数回初期化すると、デバイスIDまたはセッションIDが一致しない場合があります。
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.49.3-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.37.0-min.js.gz"></script>
<script>
// sampleRate: 1 records 100% of sessions for initial testing; lower this for production. The SDK default (0) records nothing.
const sessionReplayTracking = window.sessionReplay.plugin({ sampleRate: 1 });
window.amplitude.add(sessionReplayTracking);
window.amplitude.init(API_KEY);
</script>
セッションリプレイの計測は、Amplitudeプロジェクトのコンテキスト内で行われます。Amplitudeは、組織レベルでリプレイ割り当てを定義します。 その結果、複数のプロジェクトにまたがって複数のセッションリプレイを実装することができ、それぞれが独自のサンプルレートを持ち、同じクォータを消費します。
Google Tag Managerとの互換性
セッションリプレイプラグインスクリプトは、ページの<head>タグに追加すると非同期に読み込まれます。その結果、この実装は Google タグマネージャーと互換性がありません。 詳細については、「Google Tag Managerを使用したセッションリプレイの実装」を参照してください。
設定
| 名前 | タイプ | 必須 | デフォルト | 概要 |
|---|---|---|---|---|
sampleRate | number | いいえ | 0 | リプレイ収集のために選択するセッションの数を制御します。 この数値は0から1の小数(例:0.4)で、Amplitudeがリプレイ収集のためにランダムに選択するセッションの割合を表します。セッションが多数ある場合、0.4ではそれらのセッションのうちの40%を選択します。このフィールドは必須ではありません。セッションリプレイではサンプルレートなどの設定のリモート設定がサポートされているためです。 |
privacyConfig | object | いいえ | undefined | CSSセレクターを使用した高度なマスキング設定をサポートします。 |
applyBackgroundColorToBlockedElements | boolean | いいえ | false | trueの場合、ビジュアルマスキングのためにブロックされた要素に背景色を適用します。これにより、どの要素がセッションリプレイによるキャプチャの対象外となっているかを確認できます。 |
debugMode | boolean | いいえ | false | APIキーのハッシュを含む[Amplitude] Session Replay Debugイベントプロパティを追加します。これは、アプリの不一致などのインストルメンテーションの問題のデバッグに役立ちます。初期設定のデバッグにのみ推奨され、本番環境用ではありません。 |
serverZone | string | いいえ | US | EUか米国か。 Amplitudeサーバーゾーンを設定します。 EUデータセンター内のAmplitudeプロジェクトの場合、これをEUに設定してください。 |
configServerUrl | string | いいえ | undefined | リモート設定を取得するためのエンドポイントURL。指定した場合、デフォルトのサーバーゾーン設定を上書きします。 |
trackServerUrl | string | いいえ | undefined | セッションリプレイデータを送信するためのエンドポイントURL。指定されている場合、Amplitudeはデフォルトのセッションリプレイエンドポイントではなく、SDKからのリクエストをそこに転送します。 |
shouldInlineStylesheet | boolean | いいえ | true | trueの場合、セッションリプレイはインライン化されたスタイルシートの内容を保存します。リプレイ中、セッションリプレイはスタイルシートをリモートで取得するのではなく、保存済みのものを使用します。これにより、スタイルシートがないためにリプレイが壊れているように見えることがなくなります。インライン化スタイルシートは、すべての場合に機能するとは限りません。 未定義の場合、セッションリプレイはスタイルシートをインライン化します。 |
storeType | string | いいえ | idb | セッションリプレイがリプレイイベントを保存する方法。idbは、セッションリプレイがキャプチャ中にすべてのイベントを送信できない場合に、IndexedDBを使用してリプレイイベントを永続化します。memoryはリプレイイベントをメモリにのみ保存するため、ページが閉じられたときにイベントは失われます。IndexedDBが使用できない場合、システムはメモリにフォールバックします。 |
performanceConfig.enabled | boolean | いいえ | true | セッションリプレイを有効にすると、ブラウザのアイドル状態にある間、イベント圧縮が発生するよう遅延します。 |
performanceConfig.timeout | number | いいえ | undefined | requestIdleCallback APIのオプションのタイムアウト(ミリ秒単位)。この値を指定すると、ブラウザがアイドル状態でない場合でも、遅延圧縮タスクを実行する前にブラウザが待機する最大時間を設定します。 |
useWebWorker | boolean | いいえ | false | Webワーカーを使用して、リプレイイベントを圧縮します。これにより、圧縮をメインスレッドから外すことでパフォーマンスが向上します。 |
APIエンドポイント
ブラウザSDKとプラグインは、次のエンドポイントを使用します。Amplitudeプロジェクトと一致する地域を選択します。
| 目的 | 米国 | 欧州連合 |
|---|---|---|
| リプレイデータの取り込み | https://api-sr.amplitude.com/sessions/v2/track | https://api-sr.eu.amplitude.com/sessions/v2/track |
| リモート設定 | https://sr-client-cfg.amplitude.com/config | https://sr-client-cfg.eu.amplitude.com/config |
ドメインプロキシを設定している場合は、これらのエンドポイントにリクエストを転送してください。デフォルトをtrackServerUrlおよびconfigServerUrlで上書きします。
代替APIエンドポイント
ブラウザのSDKのネットワークに関するガイダンスには、次のエンドポイントファミリーも含まれます。これらのアドレスにリクエストを送信する実装では、対応するドメインをプロキシとCSPの設定に含めてください。
| 目的 | 米国 | 欧州連合 |
|---|---|---|
| リプレイデータの取り込み | https://api-secure.amplitude.com/sessions/track | https://api.eu.amplitude.com/sessions/track |
| リモート設定 | https://api-secure.amplitude.com/sessions/config | https://api.eu.amplitude.com/sessions/config |
デフォルトのセッションイベントを追跡
セッションリプレイでは、デフォルトでセッショントラッキングが有効になっています。これにより、セッションリプレイはセッション開始イベントとセッション終了イベントを確実にキャプチャします。セッションリプレイを実装する前にこれらのイベントをキャプチャしなかった場合、イベント量が増加することが予想されます。セッション追跡の詳細については、「ブラウザ SDK 2.0 | セッションの追跡」を参照してください。
Browser SDK設定を使用して、セッショントラッキングを暗黙的に有効にします。
amplitude.init(API_KEY, USER, {
autocapture: {
sessions: true,
},
});
セッション開始イベントとセッション終了イベント
プラグインバージョン 1.12.1 以降、セッションリプレイはデフォルトで Session Start および Session End イベントをキャプチャしなくなりました。これらのイベントのキャプチャを有効にするには、forceSessionTracking: true を設定します。
const sessionReplayTracking = window.sessionReplay.plugin({
forceSessionTracking: true, // Enable capture of Session Start and Session End events
sampleRate: 1, // 100% sample rate, should reduce for production traffic.
});
Amplitude では、リプレイを再生できるようにするには、キャプチャされたセッションで少なくとも 1 つのイベントが必要です。
シングルページのアプリナビゲーション
セッションリプレイは、新しいページを読み込まない変更を含め、変更のたびにページの URL を記録します。 Recorderは、history.pushStateおよびhistory.replaceStateをラップし、popstateおよびhashchangeイベントをリッスンします。これらの任意変更が発生するとlocation.href、セッションリプレイは新しいURLをリプレイに記録します。
これには、SvelteKitのpushStateから$app/navigationへの遷移やNext.js Pages Routerのrouter.push(url, undefined, { shallow: true })のように、アプリがルートを変更せずにURLを更新する浅いルーティング(shallow routing)が含まれます。このリプレイは、浅いルート変更後のすべての情報を新しいURLに帰属させます。ヒートマップは、各クリックが発生する際に location.href の URL を使用するため、浅いルート変更後のクリックは、新しい URL に対してカウントされます。
たとえば、スクリプトがセッションリプレイでラップされていない履歴メソッドを呼び出したため、セッションリプレイがURLの変更を逃した場合は、enableUrlChangePollingをtrueに設定します。その後、セッションリプレイは履歴イベントを確認するのではなく、一定の間隔でlocation.href確認します。urlChangePollingIntervalを使用して間隔をミリ秒単位で設定します。デフォルトは 1000 です。
const sessionReplayTracking = sessionReplayPlugin({
enableUrlChangePolling: true,
urlChangePollingInterval: 1000,
});
画面上のデータをマスクする
セッションリプレイ SDKを使用すると、3通りの方法でユーザー入力、テキスト、およびその他のHTML要素をマスクすることができます。
| エレメント | 概要 |
|---|---|
<input> | デフォルトでは、セッションリプレイはすべてのテキスト入力フィールドをマスクします。ユーザーが入力フィールドにテキストを入力すると、セッションリプレイはテキストの代わりにアスタリスクをキャプチャします。 テキスト入力のマスクを解除するには、.amp-unmaskクラスを追加します。例:<input class="amp-unmask">。 |
| テキスト | 入力要素以外の要素内のテキストをマスクするには、.amp-maskクラスを追加します。たとえば、<p class="amp-mask">Text</p>です。 マスクされている場合、セッションリプレイはマスクされたテキストを一連のアスタリスクとしてキャプチャします。 |
| テキスト以外の要素 | テキスト以外の要素をブロックするには、.amp-blockクラスを追加します。たとえば、<div class="amp-block"></div>です。 セッションリプレイは、ブロックされた要素を同じ寸法のプレースホルダに置き換えます。 |
セッションリプレイのプライバシー設定で、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)、またはデータ属性を指定します。
データ属性は、クラス名がハッシュ処理のために頻繁に変更される場合に役立ちます。 データ属性を使用するには、任意の HTML 要素に data-amp-unmaskまたはdata-amp-mask などのカスタム属性を追加します。 たとえば<textarea data-amp-unmask></textarea>のように記述し、その後セレクタを指定する際に属性を角括弧で囲みます:[data-amp-unmask]。
リモート設定
。リモート設定を有効にしてもロードに失敗した場合、セッションリプレイはセッションをキャプチャしません。これにより、管理インターフェイスで定義したプライバシー設定なしでのキャプチャが行われなくなります。
ユーザーのオプトアウト
セッションリプレイプラグインはブラウザSDKoptOutの設定に従っており、ユーザーによるオプトアウト自体をサポートしていません。
コンテンツセキュリティポリシー(CSP)
ウェブアプリケーションで厳格なコンテンツセキュリティポリシーを使用している場合は、実装で使用しているドメインをAPIエンドポイントで許可します。
必要な CSP ディレクティブ
CDN読み込みにはscript-src、取り込みおよびリモート設定にはconnect-src、useWebWorkerを有効にする場合はworker-srcを追加してください。
CSP ディレクティブのリファレンス
| ディレクティブ | ドメイン | 要件 |
|---|---|---|
script-src | https://cdn.amplitude.com | AmplitudeのCDNからブラウザSDKまたはプラグインをロードする際に必須です。 |
connect-src | https://api-sr.amplitude.comおよびhttps://sr-client-cfg.amplitude.com | USリプレイの取り込みとリモート設定。 |
connect-src | https://api-sr.eu.amplitude.comおよびhttps://sr-client-cfg.eu.amplitude.com | serverZone: "EU"の場合は、EUリプレイの取り込みとリモート設定。 |
connect-src | https://api-secure.amplitude.com | 代替のUS APIエンドポイントを使用する実装に必須です。 |
connect-src | https://api.eu.amplitude.com | 代替EU APIエンドポイントを使用する実装に必須です。 |
worker-src | blob: | リプレイイベント圧縮のをuseWebWorkerを有効にしている場合に必須です。 |
CSPヘッダーの例
US取り込みとリモート設定の場合:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.amplitude.com https://sr-client-cfg.amplitude.com; worker-src 'self' blob:;
EU取り込みとリモート設定の場合:
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.eu.amplitude.com https://sr-client-cfg.eu.amplitude.com; worker-src 'self' blob:;
代替USエンドポイントを使用した実装の場合:
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:;
configServerUrlまたはtrackServerUrlでカスタムエンドポイントを指定する場合は、対応するデフォルトドメインの代わりに、これらのドメインをconnect-srcに追加してください。
EU域内のデータレジデンシー
セッションリプレイは、EUデータセンターを使用するAmplitudeのお客様が利用できます。初期化時にserverZone設定オプションを EUに設定します。 例えば:
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
serverZone: "EU", // [tl! ~~]
}).promise;
サンプリングレート
デフォルトでは、セッションリプレイはリプレイ用にセッションの0%をキャプチャします。Amplitudeの新しいアカウントスニペットを使用して計測した場合、テストを容易にするためにサンプルレートはデフォルトで1(セッションの100%)に設定されています。セッションリプレイの設定ページからサンプルレートを更新するか、sampleRate設定オプションを使用して、セッションリプレイがキャプチャするセッション総数の割合を設定します。例えば:
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
sampleRate: 0.01,
}).promise;
手動および動的サンプル設定、クォータ計画、リモート設定の優先順位については、セッションリプレイの設定を参照してください。
リプレイ収集を無効にする
セッションリプレイを有効にした後は、次のいずれかの条件を満たすまでサイト上で実行されます。
- ユーザーがサイトを離れる。
amplitude.remove(sessionReplayTracking.name)呼び出します。
これらの例では、初期化コードで変数 sessionReplayTracking を使用していることを前提としています。
ユーザーがサイトの制限付きエリアに移動する前にamplitude.remove('sessionReplayTracking')を呼び出し、ユーザーがそのエリアにいる間はリプレイ収集を無効にします。
リプレイ収集を再開するには、amplitude.add(sessionReplayTracking) を呼び出してプラグインを再追加します。
amplitude.add() はパラメータとしてオブジェクト型Pluginを取り、パラメータとして文字列を取ります。この文字列はamplitude.remove()削除したいプラグインの名前です。
amplitude.remove()を呼び出す前に、必ずamplitude.add()が終了するまで待機してください。そうしないと、コンソールに次のエラーが表示される可能性があります: TypeError: Cannot read properties of undefined (reading 'teardown')。 このためには、次のいずれかの例に示すように、promiseプロパティを使用します。
await amplitude.add(sessionReplayTracking).promise;
await amplitude.remove(sessionReplayTracking.name).promise;
const addPromise = amplitude.add(sessionReplayTracking).promise;
addPromise.then(() => {
amplitude.remove(sessionReplayTracking.name).promise;
});
また、Amplitude 実験などのフィーチャーフラグプロダクトを使用して、場所などの基準に基づいてリプレイ収集を有効または無効にするロジックを作成することもできます。たとえば、特定のユーザーグループを対象とするフィーチャーフラグを作成し、それを初期化ロジックに追加します。
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);
if (nonEUCountryFlagEnabled) {
// Create and Install Session Replay Plugin
const sessionReplayTracking = sessionReplayPlugin({
sampleRate: 0.5,
});
amplitude.add(sessionReplayTracking);
}
データリテンション
セッションリプレイは、プライバシーリクエストと削除リクエストにAmplitudeのツールとAPIを使用します。キャプチャを実装する際には、同意ガイダンスを確認してください。
リテンション期間
デフォルトのリテンション、延長されたリテンション、およびリテンションの変更の適用開始日については、セッションリプレイのデータライフサイクルリファレンスを参照してください。
DSAR API
セッションリプレイデータライフサイクルリファレンスは、DSAR APIが返すメタデータを説明しています。
データの削除
ユーザーとプロジェクトの削除動作については、セッションリプレイのデータ削除を参照してください。
ボットフィルター
ボットフィルタリングとプロパティフィルタの制限については、セッションリプレイのボットフィルタリングを参照してください。
セッションリプレイストレージ
セッションリプレイはユーザーのブラウザにクッキーを設定しません。 代わりに、デフォルトでIndexedDBという名前のブラウザのストレージオプションに依存します。このオプションは、ユーザーがブラウザのタブに移動したり、タブを閉じて再開したりするセッション期間中に、継続的なリプレイ収集を可能にします。SDKはIndexedDBに保存されているデータをクリーンアップするため、これらのデータがユーザーのディスクスペースに影響を与えることはありません。
環境がIndexedDBをサポートしていない場合、セッションリプレイはメモリ内ストレージオプションにフォールバックします。メモリ内ストレージは耐久性が低く、ユーザーがブラウザウィンドウを閉じるとデータは失われます。メモリ内ストレージを強制するには、storeType設定オプションを'memory'に設定してください。
ユーザーがサイト上のすべてのクッキーをオプトアウトした場合、optOut設定オプションを使用して、そのユーザーのリプレイ収集を無効にします。
IndexedDBのベストプラクティス
IndexedDBが初期化され、適切に動作することを確認するには:
CSPヘッダーを確認して、制限的すぎないことを確認してください。
default-srcディレクティブおよびscript-srcディレクティブで、必要なソースが許可されていることを確認してください。同じオリジン内でIndexedDB操作を実行します。クロスオリジン制限は、IndexedDB操作をブロックする可能性があります。
ユーザーがIndexedDBをサポートする最新のブラウザを使用していることを確認します。Amplitudeでは、Chrome、Firefox、Safari、Edge、またはOperaの最新バージョンを推奨します。
クッキー
セッションリプレイ は Cookie を直接使用しないため、Cookie のサイズに影響を与えません。ブラウザ SDK はセッション管理のために Cookie を使用します。
既知の制限事項
セッションリプレイを実装する際には、次の制限事項に注意してください。
- セッションリプレイは、複数のプロジェクトにわたって 1 人のユーザーからのリプレイを統合しません。 例えば:
- マーケティングサイトとウェブアプリケーションを別々のAmplitudeプロジェクトとして計測し、それぞれでセッションリプレイを有効にすることができます。
- 既知のユーザーがマーケティングサイトから操作を開始し、ウェブアプリケーションにログインします。
- Amplitudeは両方のセッションをキャプチャします。
- 各セッションのリプレイはホストプロジェクトに表示されます。
- セッションリプレイは次のHTML要素をキャプチャできません:
- キャンバス。
- WebGL。
objectFlash、Silverlight、Java などのプラグインを含むタグ。セッションリプレイはobject type="image"をサポートしています。- Lottie アニメーション。
crossOriginIframes.enabled: trueを使用してセッションリプレイ SDK をロードしないクロスオリジン<iframe>要素(Stripe や Google マップなどのサードパーティ製の埋め込みなど)。ファーストパーティ製のクロスオリジンiframeをキャプチャするには、クロスオリジンiframe録画に移動してください。- 認証を必要とするアセット(フォント、CSS、画像など)。
- セッションリプレイは広告ブロッキングソフトウェアと互換性がありません。
複数のAmplitudeインスタンス
セッションリプレイは、Amplitude SDKの単一インスタンスへの接続をサポートしています。アプリケーションが複数のインスタンスを使用している場合は、プロジェクトに関連性の高いインスタンスでセッションリプレイを開始するようにしてください。
<script>
const sessionReplayTracking = window.sessionReplay.plugin();
const instance = window.amplitude.createInstance();
instance.add(sessionReplayTracking);
instance.init(API_KEY);
<script>
トラブルシューティング
欠落している、不完全な、または利用できないリプレイについては、セッションリプレイのトラブルシューティングを参照してください。取り込みのステータスについては、セッションリプレイ取り込みモニタリングを使用してください。
CSS のスタイル設定がリプレイに表示されない
セッションリプレイは、サイト上のCSSファイルやその他の静的アセットへの参照を保存し、それらの参照を使用してリプレイを再構築します。 ファイルが移動された場合や、認証が必要な場合、Amplitudeが再生の期間中にそれらのファイルをロードできない可能性があります。
- サイト上のアセットが移動または名前が変更されました。 これは、アプリケーションの新しいバージョンをデプロイするときに発生することがあります。
- サイト上のアセットはアクセス制御の背後にあるため、Amplitudeはそれらを取得できません。
CSS読み込みに関する問題を解決するには:
ドメインが一般公開されていることを確認してください。 ローカル環境で作業している場合、Amplitudeは
localhostに保存されているアセットにアクセスできない場合があります。CDNは古いリプレイ用に古いスタイルシートを記録しておく必要があります。同じスタイルシートのコンテンツが時間の経過とともに変化する場合は、アセットのURLに固有の文字列またはハッシュを追加してみてください。例:
stylesheet.css?93f8b89。サーバーの CORS 設定で許可されているドメインのリストに
app.amplitude.comまたはapp.eu.amplitude.comを追加します。外部スタイルシートをセッションリプレイでアクセスできるようにします。 セッションリプレイが外部スタイルシートを確実にキャプチャできるようにするには、コード内の
<link rel="stylesheet">要素にcrossorigin="anonymous"属性を追加してください。これによりブラウザは認証情報を送信せずにCSSをロードするよう指示され、オリジン間でスタイルシートルールにアクセスできるようになります。この属性がない場合、Google Chrome などのブラウザはこれらのルールへのプログラムによるアクセスをブロックします(たとえば、
stylesheet.cssRulesを読み取ろうとする試みは失敗します)。これらの制限により、セッションリプレイがスタイル情報をキャプチャできないことがあり、その結果、ビジュアル再生が不完全または破損する可能性があります。
キャプチャセッションに含まれる情報は限られています
Amplitudeは、セッションリプレイがセッションをキャプチャするときに自動的に[Amplitude] Replay Capturedイベントを作成します。実装でこのイベントが表示されない場合、ファネル分析、セグメンテーション、ジャーニーチャートなどのAmplitudeの分析ツールでリプレイが正しく表示されない可能性があります。セッションリプレイは、引き続きセッションリプレイホームページまたはユーザープロフィールページで確認できます。このイベントが表示されない場合は、Amplitudeサポートにお問い合わせください。
ブラウザSDK以外の方法を使用してイベントを計測する場合は、セッションリプレイStandalone SDKの使用を検討してください。
リプレイの長さとセッション時間が一致しません
場合によっては、リプレイの長さが[Amplitude] End Sessionおよび[Amplitude] Start Sessionイベント間の時間を超えることがあります。これは、ユーザーがブラウザやブラウザのタブを閉じて[Amplitude] End Sessionが発生したものの、Browser SDKとセッションリプレイプラグインがまだそれを処理していない場合に発生します。ユーザーがそのページを再度訪問すると、SDKとプラグインがイベントを処理し、リプレイとともにAmplitudeに送信します。 このシナリオは、End Session Client Event TimeとClient Upload Timeの間に不一致が見られる場合に発生したことを確認できます。
セッションリプレイは、以下の理由でAmplitudeに表示されない場合があります。
- コンテンツのセキュリティポリシー
- ブロックされたJavaScript
- 現在のセッションで、ブラウザSDK経由でトリガーされたイベントがない
- サンプリング
コンテンツのセキュリティポリシー
セッションリプレイのスクリプトをサイトに追加したら、セッションリプレイ 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がブロックされている可能性があります。ブラウザの開発者ツールをチェックして、リクエストが失敗したかどうかを確認し、失敗した場合は、ブロックされたドメインに例外を追加します。
現在のセッションで、ブラウザSDK経由でトリガーされたイベントがない
セッションリプレイを使用するには、ユーザーのセッション内の少なくとも1つのイベントに[Amplitude] Session Replay IDプロパティが含まれている必要があります。Browser SDKのSession StartおよびSession Endイベントには、デフォルトでこのプロパティが含まれています。Amplitude Browser SDK 2以外のSDKを使用してイベントをインストルメントする場合は、セッションリプレイ Standalone SDKを使用し、必要なイベントプロパティを使用してイベントにタグを付けてください。
ローカルテストの場合は、Session Startイベントを強制的に実行して、セッションリプレイが機能することを確認します。
- ブラウザの開発者ツールを開き、
AMP_で始まるクッキーをすべて削除します。 - 開発者ツールを閉じ、ページを更新します。
- Amplitudeの場合は、ユーザー検索イベントストリームに、
[Amplitude] Session Replay IDプロパティを含むセッション開始イベントが表示されます。処理後、そのセッションの「Play Session」ボタンが表示されます。
サンプリング
セッションリプレイのデフォルトsampleRate値は0です。レートをより高い数値に更新してください。 詳細については、サンプリングレートを参照してください。
一部のセッションには、セッションリプレイIDプロパティが含まれていません。
セッションリプレイでは、セッション内のすべてのイベントに[Amplitude] Session Replay IDプロパティがある必要はなく、セッション内の1つのイベントに含まれていれば動作します。セッションリプレイに接続しているソースとは異なるソースを使用してイベントをインストルメントする場合、このプロパティは存在しない場合があります。 たとえば、アプリケーションがBrowser 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.