セッションリプレイ（Session Replay）の導入方法¶

設定¶

表の interval/cooldown のデフォルト値は Canvas 2D に適用されます。WebGL プラグインでこれらの個別項目が明示的に設定されていない場合、より保守的な GPU 読み取りバックリズムが保持され、readPixels のコストがデフォルトで拡大されるのを防ぎます。

表のデフォルト値は、low、medium、high の文字列プリセットを使用しない場合に適用されます。文字列プリセットは、品質、sampling、interval、cooldown、unchanged/failure backoff、max-per-run を同時に置き換えます。明示的な個別設定はプリセットの対応する値を上書きします。画像品質のみを変更したい場合は、replayCanvasQuality に 0 から 1 の間の数値を渡します。完全なマトリックスは Canvas 録画ユーザーガイド を参照してください。

Canvas 2D 録画設定は SDK 3.3.0 から利用可能です。WebGL Replay は SDK 3.3.7 から提供され、RUM メインパッケージのバージョン >= 3.3.7 が必要です。また、WebGL プラグインはメインパッケージと同じ SDK リリースバージョンを使用することを推奨します。

Session Replay を有効にする¶

これまで使用していた SDK の導入方法に従い、NPM パッケージを > 3.0.0 バージョンに置き換えるか、CDN リンクを https://static.guance.com/browser-sdk/v3/dataflux-rum.js に置き換えてください。SDK の init() を実行しただけでは Session Replay Record データは自動収集されません。startSessionReplayRecording を実行してデータ収集を開始する必要があります。これは、特定の条件下でのみ Session Replay Record データを収集したい場合に便利です。例：

// ユーザーログイン後の操作データのみ収集
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

Session Replay のデータ収集を停止する必要がある場合は、stopSessionReplayRecording() を呼び出して停止できます。

NPM¶

@cloudcare/browser-rum パッケージを導入し、@cloudcare/browser-rum のバージョンが > 3.0.0 であることを確認してください。録画を開始するには、初期化後に datafluxRum.startSessionReplayRecording() を実行してください。

import { datafluxRum } from '@cloudcare/browser-rum'

datafluxRum.init({
  applicationId: '<DATAFLUX_APPLICATION_ID>',
  datakitOrigin: '<DATAKIT ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  trackInteractions: true,
})

datafluxRum.startSessionReplayRecording()

CDN¶

CDN アドレスを https://static.guance.com/browser-sdk/v2/dataflux-rum.js から https://static.guance.com/browser-sdk/v3/dataflux-rum.js に置き換え、DATAFLUX_RUM.init() の実行後に DATAFLUX_RUM.startSessionReplayRecording() を実行してください。

<script
src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
    applicationId: '<DATAFLUX_APPLICATION_ID>',
    datakitOrigin: '<DATAKIT ORIGIN>',
    service: 'browser',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    trackInteractions: true,
})

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

エラー関連の Session Replay データのみを収集する方法（SDK バージョン要件 ≥3.2.19）{#sessionReplayOnErrorSampleRate}¶

機能説明¶

ページでエラーが発生すると、SDK は自動的に次の操作を実行します。

1. 遡及収集：エラー発生前 1 分間 の完全なページスナップショットを記録
2. 継続録画：エラー発生時点からセッション終了まで継続的に記録
3. スマート補完：独立したサンプリングチャネルによりエラーシナリオの完全なカバレッジを確保

設定例¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// SDK のコア設定を初期化
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // 必須パラメータ
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

   // 環境識別子
   service: 'browser',
   env: 'production',
   version: '1.0.0',

   // サンプリング戦略設定
   sessionSampleRate: 100,          // 全量ベースセッション収集 (100%)
   sessionReplaySampleRate: 0,       // 通常の録画サンプリングを無効化
   sessionReplayOnErrorSampleRate: 100, // エラーシナリオは 100% サンプリング

   // 補助機能
   trackInteractions: true          // ユーザー行動追跡を有効化
});

// 録画エンジンを強制起動（必須）
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas 録画について¶

Canvas 録画はデフォルトでは自動的に有効になりません。実際に動作させるには、少なくとも以下の条件をすべて満たす必要があります。

• Session Replay がサンプリングされていること
• つまり sessionReplaySampleRate > 0 であるか、sessionReplayOnErrorSampleRate にヒットしていること
• startSessionReplayRecording() が呼び出されていること
• replayCanvasEnabled: true が設定されていること
• 対象要素が Canvas 2D であること。WebGL/WebGL2 の場合は、さらに WebGL Replay プラグインの登録が必要です。

manual モードを使用する場合は、さらにビジネスコードから明示的に呼び出す必要があります。

datafluxRum.snapshotCanvas(canvas)

Canvas 関連パラメータのうち必須とみなすべきもの¶

実際に導入する際は、以下の項目を必須とみなすことを推奨します。

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

replayCanvasMode === 'auto' の場合は、さらに以下を明示的に設定します。

• replayCanvasSampling
• 正の数値：自動スナップショットパスを選択します。2 から開始することを推奨します。
• 'all'：より高忠実度の自動録画。描画プロセスの再現性を重視するページに適しています。
• replayCanvasAutoInterval
• 自動スナップショットのスケジューリング間隔を制御します。数値サンプリング自体は Canvas 2D の頻度を制御しません。

3つの推奨最小設定¶

手動録画¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

自動スナップショット¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 250,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

自動高忠実度録画¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CSP シナリオ¶

サイトの CSP で worker-src blob: が許可されていない場合は、次のように設定できます。

datafluxRum.init({
  // ...
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

注意点：

• replayCanvasWorkerUrl は Canvas スナップショットのエンコードにのみ影響します
• workerUrl を代替するものではありません
• すべての Canvas フレームが Canvas Worker を使用するわけではありません

詳細は CSP セキュリティポリシー を参照してください。

Canvas 2D、WebGL/WebGL2 の完全な機能範囲、オプションのプラグイン連携、パフォーマンスに関する推奨事項は Canvas 録画ユーザーガイド を参照してください。WebGL プラグインは RUM メインパッケージと同じ SDK バージョンを使用し、WebGL エンジンが context を作成したり描画メソッドをキャッシュしたりする前に RUM init() を完了する必要があります。

无界（Wujie）マイクロフロントエンドと open Shadow DOM¶

RUM SDK 3.3.11 以降、Session Replay は iframe JavaScript realm によって作成され、その後現在のページの open ShadowRoot にアタッチされたネイティブフォーム要素と Canvas を認識できるようになりました。このような構造は、无界（Wujie）マイクロフロントエンドでよく見られます。要素は iframe realm のプロトタイプを保持していますが、現在のページからアクセス可能な Shadow DOM コンテンツに属しています。

• input、textarea、select のユーザー入力と変更イベントがリプレイに取り込まれます。要素が Replay DOM に追加された後、JavaScript で value、checked、selectedIndex プロパティを変更しても記録できます。
• open ShadowRoot 内の DOM 構造およびその後の DOM 変更がリプレイに取り込まれます。
• Canvas は引き続き replayCanvasEnabled: true の設定が必要で、本ページで前述した収集モードと予算に従います。replayCanvasSampling: 'all' で Canvas コマンド収集が有効な場合、現在のページの realm の Canvas は引き続き描画コマンドを収集し、iframe 外の realm の Canvas は自動的にビットマップスナップショットでフォールバックします。
• mode: 'closed' の Shadow DOM、および iframe 内部のドキュメントに残っているコンテンツは、このサポート対象外です。

ここでの「iframe realm」は、要素が iframe の JavaScript 環境によって作成されたことを示すだけで、SDK が iframe 内部のドキュメントを録画することを意味するわけではありません。現在のページからアクセス可能な open ShadowRoot にアタッチされたコンテンツのみが、通常のページ DOM として Session Replay に取り込まれます。

注意事項¶

一部の HTML 要素が再生時に表示されない¶

セッションリプレイは iframe 内部のドキュメントを記録しません。また、ビデオやオーディオのメディアコンテンツも収集しません。関連する要素自体や再生状態は記録に含まれる可能性があります。現在の実装では、アクセス可能な open Shadow DOM をサポートしています。mode: 'closed' の Shadow DOM は収集を保証できません。Web Components が完全に記録できるかどうかは、Shadow Root がオープンであるかどうか、および内部で使用されるコンテンツタイプに依存します。

FONT または IMG が正しく表示されない¶

Session Replay はビデオではなく、DOM スナップショットに基づいて再構築された iframe です。そのため、リプレイはページのさまざまな静的リソース（font や image）に依存します。

以下の理由により、リプレイ時に静的リソースが利用できない可能性があります。

• 静的リソースがすでに存在しない場合（例：以前のデプロイの一部であった）
• 静的リソースにアクセスできない場合（例：認証が必要、または内部ネットワークからのみアクセス可能）

• CORS（特にウェブフォント）により、ブラウザが静的リソースをブロックする場合

• リプレイ時は、guance.com のサンドボックス環境に基づく iframe であるため、特定のドメインが許可されていない場合、ブラウザがリクエストをブロックします。

• Access-Control-Allow-Origin ヘッダーで guance.com がサイトが依存するすべての font や image 静的リソースにアクセスできるように許可し、リプレイ時にこれらのリソースにアクセスできるようにしてください。

詳細については、クロスオリジンリソース共有 を参照してください。

CSS スタイルが正しく適用されない、またはマウスホバーイベントがリプレイされない¶

font や image とは異なり、Session Replay Record は CSSStyleSheet インターフェースを利用して、適用されたさまざまな CSS ルールをレコードデータの一部としてバンドルしようとします。これが実行できない場合、CSS ファイルのリンクを記録するフォールバックが行われます。

正しいマウスホバーサポートを得るには、CSS ルールに CSSStyleSheet インターフェースからアクセスできる必要があります。

スタイルファイルがウェブページとは異なるドメインでホストされている場合、CSS ルールへのアクセスはブラウザのクロスオリジンセキュリティチェックの対象となり、crossorigin 属性を使用して CORS を利用するスタイルファイルをロードするようブラウザに指定する必要があります。

例えば、アプリケーションが example.com ドメインにあり、link 要素を介して assets.example.com の CSS ファイルに依存している場合、crossorigin 属性を anonymous に設定する必要があります。

<link rel="stylesheet" crossorigin="anonymous"
      href="https://assets.example.com/style.css">

さらに、assets.example.com で example.com ドメインを許可します。これにより、リソースファイルが Access-Control-Allow-Origin ヘッダーを設定することで、リソースを正しくロードできるようになります。

関連情報¶