Web アプリケーションの統合¶

このページの設定が完了すると、Browser RUM SDK は自動的にページの View、リソースリクエスト、フロントエンドエラー、ユーザー操作を収集し、データをGuanceに報告します。

統合パスの選択¶

まずアプリケーションの形態に応じてエントリを選択し、View の重複設定やサーバーサイドレンダリング段階でのブラウザ API へのアクセスを避けてください。

統合情報の準備¶

1. 「RUM > アプリ一覧 > アプリを作成 > Web」に移動します。
2. アプリを作成し、コンソールで生成された applicationId、env、version などの設定を取得します。

3. データ報告方式を選択します。

4. 公開 OpenWay：site と clientToken を取得します。DataKit のデプロイは不要です。

5. DataKit 直結：datakitOrigin を準備します。DataKit で RUM コレクター を有効にし、インターネットからアクセス可能で IP 地理情報データベースをインストール するよう設定します。

報告方式¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

SDK の統合¶

NPM 統合¶

フロントエンドプロジェクトに SDK をインストールしてインポートします。

npm install @cloudcare/browser-rum @cloudcare/browser-core

プロジェクト内で SDK を初期化します。

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

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 同期ロード¶

HTML ファイルにスクリプトを追加します。

<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: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN 非同期ロード¶

HTML ファイルにスクリプトを追加します。

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

上記の例では公開 OpenWay を使用しています。DataKit 直結を使用する場合は、site と clientToken を削除し、代わりに datakitOrigin を設定してください。

統合の確認¶

1. SDK を統合したページを開き、ページ遷移、ボタンクリック、API リクエストを 1 回ずつ実行します。
2. ブラウザの開発者ツールの Network タブで /v1/write/rum をフィルタリングし、成功した報告リクエストが存在することを確認します。
3. Console を確認し、Application ID is not configured、datakitOrigin or site is not configured などの初期化エラーがないことを確認します。
4. 「RUM > アプリ一覧」に移動し、対応する Web アプリケーションを開き、エクスプローラーで service、env、version でフィルタリングして、View、Resource、または Action データが存在することを確認します。

よく使われるオプション設定¶

基本データの確認が成功したら、必要に応じて他の機能を有効にします。

トレーシング設定（オプション）¶

NPM + TypeScript 統合の場合、traceType には対応するブランドの browser-core パッケージからインポートした TraceType 列挙型を使用する必要があります。

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

TraceType.DDTRACE のランタイム値は "ddtrace" のままです。CDN 統合にはモジュールインポートがないため、明示的に設定する場合は対応するランタイム文字列を使用します。トレーシングを有効にした後は、API サーバー側で対応する Trace Header を許可する必要もあります。詳細は APM と RUM の連携方法 を参照してください。

通常の Session がサンプリングに該当しない場合でも、Trace Header をバックエンドに渡す必要がある場合は、allowTraceHeaderWithoutSession を明示的に有効にできます。

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

有効にすると、SDK は allowedTracingUrls に一致する XHR および Fetch リクエストにのみ Trace Header を注入します。この設定は RUM Session を作成したり強制したりせず、サンプリングされていない Session の View、Error、Resource、Action データを報告することもありません。API サーバーは選択した traceType に対応するリクエストヘッダーを許可する必要があります。クロスオリジンリクエストの場合は CORS も正しく設定する必要があります。

パラメータ設定¶

初期化パラメータ¶

low、medium、high の文字列プリセットを使用しない場合、Canvas 自動スケジューリングのベースラインは次のようになります。 sampling 2、各 Canvas の目標 interval 250 ms、cooldown 250 ms、unchanged backoff 3000 ms、failure backoff 5000 ms、1 ラウンドあたり最大 2 つの Canvas。文字列プリセットはこれらの予算とエンコーディング品質を同時に置き換えます。複数の Canvas は公平なラウンドロビンとグローバル収集予算の制限も受けます。明示的な個別設定は、プリセット内の対応する値を上書きします。完全なプリセットマトリックスについては、Canvas 録画マニュアルを参照してください。

上記の高頻度スケジューリングベースラインは Canvas 2D 用です。WebGL プラグインは、interval/cooldown が明示的に設定されていない場合、より保守的な GPU 読み戻しレートを継続します。明示的な個別設定によってのみ、それぞれが上書きされます。

site パラメータの処理¶

ランタイム Session 制御¶

RUM SDK 3.3.6 で startSession() が追加されました。呼び出すとすぐに現在の Session を終了し、現在のサンプリング設定に従って新しい Session を開始します。次のユーザー操作を待つ必要はありません。

datafluxRum.startSession()

ランタイムの sessionSampleRate を同時に上書きすることもできます。

datafluxRum.startSession({
  sessionSampleRate: 100,
})

サンプリング率は 0 から 100 の間でなければなりません。この上書き値は、今回および後続の自動継続 Session に使用されます。完全な RUM パッケージと軽量 RUM パッケージの両方でこの API をサポートしています。詳細なセマンティクスと使用シナリオについては、ランタイムでの Session 再開始を参照してください。

必要に応じて高度な機能を有効にする¶

エラーセッションイベントのみを収集¶

ページでエラーがトリガーされると、SDK は自動的に次の処理を実行します。

• 継続的記録：エラー発生時から、セッションの全ライフサイクルデータを完全に記録します。
• 正確な補償：独立したサンプリングチャネルにより、エラーシナリオの漏れを防ぎます。

設定例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

上記の例では公開 OpenWay を使用しています。DataKit 直結の場合は、基本統合の例に従って報告アドレスフィールドを置き換えてください。

データ圧縮¶

大量の静的リソース（JS、CSS、画像など）を収集し、かつ全量収集を有効にしている場合、SDK は初期化後に多くのデータを生成する可能性があり、リクエストが滞留し、アプリケーションスレッドの状態に影響を与える可能性があります。

compressIntakeRequests: true を設定すると、SDK は Web Worker 内で deflate を使用して報告データを圧縮し、リクエストサイズとリクエスト数を削減します。

設定例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

注意事項¶

1. データ圧縮ロジックは Web Worker で実行されます。CSP セキュリティポリシーが有効な場合は、worker-src で blob: を許可する必要があります。詳細は CSP セキュリティポリシーについて を参照してください。
2. SDK は workerUrl 設定項目で自己ホストの Worker アドレスを指定できます。
3. この機能を使用するには、SDK バージョン >= 3.2 が必要です。

カスタムデータとイベント¶

基本統合ページでは、すべての共通 API を再度展開しません。ビジネス目標に応じて対応するページに移動すると、CDN、NPM、および完全なパラメータ例が表示されます。

• ユーザー操作の追跡：クリックの自動収集、Action 名の定義、カスタム Action の追加。
• カスタムユーザー識別子：ログイン後にユーザーを設定し、ログアウトやアカウント切り替え時にユーザーをクリアします。
• グローバルコンテキスト：後続のすべての RUM イベントに安定したビジネスディメンションを追加します。
• カスタム Action の追加：ページのクリックでは表現できないビジネス操作を記録します。
• カスタム Error の報告：すでにキャッチされた、またはビジネス側で能動的に識別された例外を報告します。

Web Session Replay¶

録画の開始¶

SDK の初期化後、startSessionReplayRecording() メソッドを呼び出してセッションリプレイの録画を開始します。特定の条件（ユーザーログイン後など）で有効にすることもできます。セッション録画の開始。

エラーに関連するセッションリプレイデータのみを収集¶

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

• 遡及収集：エラー発生前の 1 分間の完全なページスナップショットを記録します。
• 継続的録画：エラー発生時からセッション終了まで継続的に記録します。
• インテリジェント補償：独立したサンプリングチャネルにより、エラーシナリオの漏れを防ぎます。

設定例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

注意事項¶

• セッションリプレイは、iframe、ビデオ、オーディオの再生内容を記録しません。Canvas はデフォルトでは収集されません。replayCanvasEnabled を個別に設定する必要があります。WebGL/WebGL2 は SDK 3.3.7 から提供され、RUM メインパッケージのバージョン >= 3.3.7 が必要です。また、互換性のある browser-rum-webgl プラグインを追加でインストールして登録する必要があります。詳細は Canvas 録画マニュアル を参照してください。
• リプレイ時に静的リソース（フォント、画像など）に正常にアクセスできるようにするために、CORS ポリシーの設定が必要になる場合があります。
• CSS スタイルとマウスホバーイベントをサポートするために、CSSStyleSheet インターフェースを介して CSS ルールにアクセスできることを確認してください。

録画状態の確認¶

window.DATAFLUX_RUM.isRecording() を呼び出して、現在のページが録画中であることを確認し、セッションリプレイエクスプローラーで対応する Session にリプレイデータが生成されていることを確認します。本番環境では、ビジネス要件に応じて sessionReplaySampleRate を調整してください。