コンテンツにスキップ

Electron モニタリング

Windows SDK は Native Bridge を介して Electron と統合します。Renderer 内の Browser RUM と Browser Logs がページデータを収集し、Electron Main Process がそのデータを Windows Native Core に渡します。Native Core がアプリケーション ID、セッション、サンプリング、グローバルコンテキスト、永続化キュー、アップロードを一元管理します。

Native SDK の初期化所有者に応じて、以下のいずれかのモードを選択します。

モード ユースケース vcpkg Feature SDK 所有者
ハイブリッドモード C++ デスクトップアプリケーションに Electron ページを埋め込む electron-adapter C++ ホスト
フルモード アプリケーション自体が Electron electron-bridge guance_windows_electron_bridge.exe

両方のモードを同時に使用することはできません。ページ側では、同じ Preload、attachWindow()、Renderer の初期化方法を共有します。

この方法は Web RUM の Electron 個別導入 とは異なります。Windows SDK 統合では、Renderer はデータを直接アップロードせず、実際のアプリケーション ID、レポートアドレス、Client Token も設定しません。

データフローは以下のとおりです。

Electron Renderer
  @cloudcare/browser-rum / @cloudcare/browser-logs コレクター
          |
          | FTWebViewJavascriptBridge.sendEvent(JSON)
          v
セキュア Preload -> ホワイトリスト IPC -> Electron Main Process
          |
          v
Windows Native Core（C++ ホストまたは Bridge EXE により初期化）
  ネイティブ RUM / Log / セッション / サンプリング / コンテキスト / 永続化 / アップロード

Electron 統合

依存関係のインストール

収集が必要な Renderer プロジェクトに Browser SDK をインストールします。

npm install @cloudcare/browser-rum @cloudcare/browser-logs@^3.3.6

Browser Log を収集しない場合は、@cloudcare/browser-logs のインストールは不要です。

クイックスタート に従って GuanceCloud vcpkg レジストリを設定します。現在の Electron Adapter は動的 x64-windows のみをサポートしています。

フルモードでは electron-bridge を使用します。

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false,
      "features": ["electron-bridge"]
    }
  ]
}

ハイブリッドモードでは electron-adapter を使用します。

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false,
      "features": ["electron-adapter"]
    }
  ]
}

vcpkg.json が配置されているディレクトリで以下を実行します。

vcpkg install --triplet x64-windows

統合時には、以下の公開エントリポイントのみを使用します。

  • electron/main/index.cjs：Main Process のフルモードおよびハイブリッドモード用エントリポイント。
  • electron/preload/standalone.cjs：アプリケーションに既存の Preload がない場合に直接使用します。
  • electron/preload/install.cjs：アプリケーションに既存の Preload がある場合、バンドラーを使用してビジネス Preload にマージします。

electron/internal/ 配下のファイルはコピー、変更、直接参照しないでください。

開発実行時はプロジェクトの vcpkg_installed ディレクトリから Adapter をロードし、パッケージ化後は process.resourcesPath からロードします。

const path = require("node:path");
const { app } = require("electron");

const sdkDirectory = app.isPackaged
  ? path.join(process.resourcesPath, "guance-windows-native")
  : path.resolve(
      __dirname,
      "../../../vcpkg_installed/x64-windows/tools/guance-windows-native",
    );

const mainAdapterPath = path.join(
  sdkDirectory,
  "electron",
  "main",
  "index.cjs",
);

開発ディレクトリの相対階層はアプリケーションの構造に合わせて調整してください。カレントワーキングディレクトリや開発機の絶対パスをハードコードしないでください。

Native Bridge の初期化

ハイブリッドモード

C++ ホストが最初に Windows SDK を初期化し、Bridge Server を既存の guance_sdk_handle にバインドします。

guance_sdk_handle sdk = guance_sdk_init(&config);

guance_electron_bridge_server_options options{};
guance_electron_bridge_server_options_init(&options);
options.pipe_name = "my-app-rum";
options.logging_enabled = 1;
options.session_replay_enabled = 0;
options.replay_privacy_level = "mask";

guance_electron_bridge_server_handle bridge =
    guance_electron_bridge_server_start(sdk, &options);

// アプリケーション終了時は、先に Bridge Server を停止し、その後 SDK をシャットダウンします。
guance_electron_bridge_server_stop(bridge);
guance_sdk_shutdown(sdk);

Electron Main Process は同じ名前の named pipe に接続します。

const { ipcMain } = require("electron");
const { connectMixedMode } = require(mainAdapterPath);

const rumBridge = await connectMixedMode({
  ipcMain,
  pipeName: "my-app-rum",
  enableAppLaunch: true,
});

ハイブリッドモードでは：

  • guance_windows_electron_bridge.exe を起動しないでください。2 つ目の SDK Handle が作成されます。
  • Electron はアプリケーション ID、DataKit/Dataway、キャッシュ、アップロード設定を渡しません。
  • C++ ホストは、SDK Handle のライフサイクルが Bridge Server よりも長いことを保証する必要があります。
  • Browser Log を収集する場合は、ネイティブのカスタムログを有効にし、logging_enabled を 1 に設定する必要があります。

フルモード

アプリケーション自体が Electron の場合、Main Process が Bridge EXE を起動および管理します。

const { app, ipcMain } = require("electron");
const { startFullMode } = require(mainAdapterPath);

const rumBridge = await startFullMode({
  ipcMain,
  nativeDirectory: sdkDirectory,
  enableAppLaunch: true,
  nativeSettings: {
    applicationId: "<rum-application-id>",
    datakitUrl: "http://127.0.0.1:9529",
    service: "electron-desktop-client",
    environment: "prod",
    version: app.getVersion(),
    cachePath: path.join(app.getPath("userData"), "native-rum-cache"),
    sampleRate: 1,
    loggingEnabled: true,
    loggingSampleRate: 1,
    replayEnabled: false,
    replaySampleRate: 1,
    replayPrivacy: "mask",
    debug: false,
  },
});

ネイティブ RUM、Log、Replay のサンプリングレートは、すべて 0 から 1 の値を取ります。アプリケーション終了時は、rumBridge.stop() が完了するのを待つ必要があります。

connectMixedMode() と startFullMode() は、デフォルトで enableAppLaunch が有効になっています。Adapter は Electron のアプリケーションライフサイクル、信頼できるウィンドウの初回フレーム、Browser View のコンテキストを組み合わせて、launch_cold、launch_hot Action を自動生成します。自動起動 Action が不要な場合は false に設定します。コールドスタートを最初の Browser View に関連付けるには、Bridge をできるだけ早期に起動または接続し、ウィンドウ作成後すぐに attachWindow() を呼び出してください。

Preload とウィンドウの統合

収集が必要な各ウィンドウは、Guance Preload をロードし、attachWindow() で信頼できるウィンドウとして登録する必要があります。以下の Electron セキュリティ設定を維持してください。

  • contextIsolation: true
  • nodeIntegration: false
  • sandbox: true

アプリケーションに既存の Preload がない場合は、standalone.cjs を直接使用します。

const standalonePreloadPath = path.join(
  sdkDirectory,
  "electron",
  "preload",
  "standalone.cjs",
);

const window = new BrowserWindow({
  webPreferences: {
    preload: standalonePreloadPath,
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
});

const detachWindow = rumBridge.attachWindow(window);
window.webContents.once("destroyed", detachWindow);

アプリケーションに既存の Preload がある場合は、electron/preload/install.cjs を webpack、esbuild などのバンドラーのビルド依存関係として設定し、ビジネス Preload 内で一度呼び出します。

const { installElectronRumPreload } = require("guance-electron-preload");

installElectronRumPreload();

ここでの guance-electron-preload は install.cjs を指すビルドエイリアスであり、npm パッケージではありません。sandbox: true を有効にする場合、最終的な Preload の成果物は webPreferences.preload で直接ロードできるバンドルである必要があります。

収集が不要なページには Guance Preload をロードせず、attachWindow() も呼び出さないでください。マルチウィンドウアプリケーションの場合、各ウィンドウを個別に登録し、破棄時に attachWindow() が返す削除関数を呼び出してください。

Renderer の初期化

モニタリングが必要な各 Renderer で Browser SDK を初期化します。Bridge モードでは applicationId は不要です。datakitOrigin は Browser SDK の初期化チェックを通過するためだけに使用され、データはこのアドレスにアップロードされません。

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

datafluxLogs.init({
  datakitOrigin: "http://127.0.0.1",
  forwardErrorsToLogs: true,
  forwardConsoleLogs: ["error", "warn"],
});

datafluxRum.init({
  datakitOrigin: "http://127.0.0.1",
});

const capabilities = JSON.parse(
  window.FTWebViewJavascriptBridge.getCapabilities(),
);
if (capabilities.includes("records")) {
  datafluxRum.startSessionReplayRecording();
}

Browser SDK は FTWebViewJavascriptBridge を検出すると Bridge 転送に切り替わり、Browser HTTP Batch を開始しません。ログのサンプリングは、ネイティブの loggingSampleRate で統一して制御することを推奨します。低い Browser sessionSampleRate を設定して二重サンプリングが発生しないようにしてください。

Session Replay は実験的機能であり、デフォルトでは無効です

Native SDK と Bridge の両方の設定で Replay が有効になっている場合のみ、getCapabilities() は records を返します。Renderer はこの機能に基づいて録画を開始するかどうかを決定する必要があり、単独で強制的に有効にすることはできません。ハイブリッドモードでは、ネイティブの Replay 設定、Bridge Server の設定、および録画のライフサイクルを一致させる必要もあります。

リソースのパッケージ化

electron-builder を使用する場合、フルモードでは SDK ツールディレクトリ全体をアプリケーションリソースに含める必要があります。

{
  "build": {
    "extraResources": [
      {
        "from": "vcpkg_installed/x64-windows/tools/guance-windows-native",
        "to": "guance-windows-native"
      }
    ]
  }
}

フルモードでは、同じ SDK バージョンの Bridge EXE、Native DLL、electron/ ディレクトリを納品する必要があります。ハイブリッドモードでは tools/guance-windows-native/electron/ のみをコピーします。Native DLL は引き続き C++ ホストの既存のデプロイフローで納品されます。カレントワーキングディレクトリや開発機の絶対パスに依存してリソースを特定しないでください。

統合の境界

  • Main Process は electron/main/index.cjs の公開インターフェースのみを使用し、独自に SDK 内部の IPC Channel を登録しないでください。
  • アプリケーション ID、Client Token、DataKit/Dataway アドレス、ネイティブセッション、完全な Native 設定を Renderer に公開しないでください。
  • Main Process は信頼できる webContents のみを登録します。リモートページでは、ナビゲーション、ポップアップ、権限、許可ドメインを制限する必要もあります。
  • トレースは引き続き Windows SDK Trace API を使用して個別に設定します。Electron Adapter はトレース設定を Renderer に注入しません。
  • Renderer の JavaScript Error と Long Task は Browser RUM が収集します。unresponsive、render-process-gone、Main Process Crash は Bridge が自動的に報告しません。必要に応じて、Electron の crashReporter や他の Crashpad サービスを個別に統合してください。

統合の検証

  1. Renderer の DevTools Network で、RUM または Log の直接送信リクエストがないことを確認します。
  2. View、Action、Resource、Error、Long Task、および 1 つの Browser Log をトリガーし、データが Guance に取り込まれることを確認します。
  3. データが Native 設定のアプリケーション ID、セッション ID、sdk_name=df_windows_rum_sdk を使用していることを確認します。
  4. Browser Log の warn ステータスが Native Log で warning として表示され、カスタム属性が保持されていることを確認します。
  5. Replay が無効の場合、getCapabilities() に records が含まれていないことを確認します。有効の場合、録画データが正常に報告されることを確認します。
  6. ハイブリッドモードで Electron ページを閉じた後、C++ SDK が引き続き動作していることを確認します。フルモードでアプリケーションを終了した後、Bridge EXE が正常に終了することを確認します。

検証には、Windows SDK リポジトリ内の Electron vcpkg Consumer Acceptance および Electron Sample を参照できます。

フィードバック

このページは役に立ちましたか？