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.50.1-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設定オプションを使用して、これらのデフォルト値を上書きできます。

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

The Session Replay SDK offers three ways to mask user input, text, and other HTML elements.

Session Replay supports setting a masking level on the Session Replay Settings screen in Amplitude. This includes Light, Medium, and Conservative settings.

Session Replay settings also enable remote masking overrides. These enable users in your organization to configure or update masking after implementation.

In the event of a conflict, Session Replay defers to the remote setting. For example:

In this example, .selector-1 has a local setting and a remote setting. The result follows the remote setting, and overrides the setting in the SDK or plugin implementation.

Specify elements to block or mask in the privacyConfig object during configuration.

// 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 selectors

Session Replay's configuration supports many types of CSS Selector. Specify an element tag (h1 or textarea), a class name (.hidden) or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use data attributes, add a custom attribute like data-amp-unmask or data-amp-mask to any HTML element. For example, <textarea data-amp-unmask></textarea>, then enclose the attribute in square brackets when you specify the selector, [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;

Data retention

Session replay uses existing Amplitude tools and APIs to handle privacy and deletion requests.

Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from the date of ingestion.

Purchase extra retention time, up to a maximum of 12 months. For more information, contact Amplitude Support.

If you purchase extra session volume, Amplitude retains raw replay data for up to 12 months from the date of ingestion. If you need a more strict policy, contact Amplitude support to set the value to 30 days.

Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.

Replays that are outside of the retention period aren't viewable in Amplitude.

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

Session Replay storage

Session Replay doesn't set cookies on the user's browser. Instead, it relies on a browser storage option called IndexedDB by default. This option enables continuous replay collection during a session in which the user navigates browser tabs or closes and reopens a tab. The SDK cleans up the data it stores in IndexedDB and shouldn't impact the user's disk space.

If the environment doesn't support IndexedDB, Session Replay falls back to an in-memory storage option. In-memory storage is less durable and data is lost when the user closes their browser window. Set the config option storeType to 'memory' to force in-memory storage.

If a user opts out of all cookies on your site, use the optOut configuration option to disable replay collection for that user.

IndexedDB best practices

To ensure that IndexedDB is initialized and working properly:

• Review CSP headers to ensure they're not overly restrictive. Ensure default-src and script-src directives allow necessary sources.

• Perform IndexedDB operations within the same origin. Cross-origin restrictions can block IndexedDB operations.

• Confirm that users use a modern browser that supports IndexedDB. Amplitude recommends the latest versions of Chrome, Firefox, Safari, Edge, or 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 を追加します。

Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the [Amplitude] Start Session and [Amplitude] End Session events. This happens when a user closes their browser or browser tab and [Amplitude] End Session occurs, but the Browser SDK and Session Replay plugin haven't yet processed it. When the user visits that page again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the End Session Client Event Time and the Client Upload Time.

Session replays may not appear in Amplitude due to:

• Content security policy
• Blocked JavaScript
• No events triggered through the browser SDK in the current session
• Sampling

Local development and focus state

The Session Replay SDK and plugin capture only the page that's in focus. When you develop locally with the browser console open, focus states may not work as expected. If you don't see replays in Amplitude, try to enable debugMode. In this mode, Session Replay ignores the focus handle and enables extra debugging information.

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

Content security policy

When you add the Session Replay script to your site, visit a page on which the Session Replay SDK is running, and open your browser's developer tools.

Check for any error messages in the JavaScript console that contain the text Content Security Policy. For example, Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy.

To resolve this error, update your site's content security policy to allow connection to Amplitude's APIs.

Blocked JavaScript

Browser extensions or network security policy may block the Session Replay SDK. Check your browser's developer tools to see if requests fail, and if so, add an exception for the blocked domains.

Sampling

As mentioned above, the default sampleRate for Session Replay is 0. Update the rate to a higher number. For more information see, Sampling rate.

Some sessions don't include the Session Replay ID property

Session replay doesn't require that all events in a session have the [Amplitude] Session Replay ID property, only that one event in the session has it. Reasons why [Amplitude] Session Replay ID may not be present in an event include:

If you instrument an event with a source different from the source you connect to Session Replay. For example, your application may send events from a backend source, rather than the Browser SDK.

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

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

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