Electron モニタリング¶

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

Native SDK の初期化主体に応じて、いずれかのモードを選択します：

2 つのモードは同時に使用できません。ページ側では、同じ 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 への統合¶

依存関係のインストール¶

Electron プロジェクトに Native Adapter と Browser SDK をインストールします：

npm install @cloudcare/electron-native-adapter @cloudcare/browser-rum @cloudcare/browser-logs

Browser Log を収集しない場合は、@cloudcare/browser-logs をインストールする必要はありません。

Browser Logs の Bridge 統合には、3.3.6 以降が必要です。

検証済みの Electron ベースラインは 22.3.27 と 43.x です。宣言されている互換範囲は ^22.3.27 || 43.x で、中間のメジャーバージョンは未検証です。Electron 22 は Windows 7 SP1 向けのレガシー互換ベースラインであり、Electron 43 は Windows 10 以降が必要です。ターゲット OS と Native Runtime の組み合わせは、引き続き検証が必要です。

npm インストールとランタイムインストーラーには Node.js 18+ が必要です。パッケージング後のアプリのユーザーが Node.js を別途インストールする必要はありません。Windows は x64、x86（Electron/Node.js では ia32）、arm64 に対応しており、ランタイムのアーキテクチャに一致する Microsoft Visual C++ v14 Redistributable と Windows Universal CRT のインストールが必要です。

リリースされる npm パッケージ自体には Native バイナリが同梱されていませんが、postinstall がプラットフォームとアーキテクチャに応じて Native Runtime をダウンロードして検証するため、ローカルでのコンパイルは不要です。フルモードでは、このランタイムがデフォルトで自動的に検出されるため、事前に vcpkg をインストールする必要はありません。Adapter は macOS にも対応しています。本ページでは Windows Native Bridge の統合について説明します。

ハイブリッドモードのみを使用する場合は、インストール前に PowerShell 環境変数 $env:GUANCE_NATIVE_SKIP_DOWNLOAD = "1" を設定することで、不要なランタイムのダウンロードをスキップできます。フルモードでのインストールに切り替える前に、この変数を削除してください。

オプション：vcpkg による Native Runtime の提供¶

ホスト側で Native SDK を保有している場合、またはランタイムを自前でビルドする必要がある場合は、クイックスタートに従って SDK の vcpkg レジストリを設定します。JavaScript Adapter は引き続き npm から個別にインストールします。フルモードのランタイムを手動で提供する場合は、electron-bridge を有効にします：

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

ハイブリッドモードでは、基本の Native パッケージのみをインストールし、Electron Feature は有効にしません：

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

vcpkg.json があるディレクトリで実行します：

vcpkg install --triplet x64-windows

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

• @cloudcare/electron-native-adapter：Main Process の統一 bootstrap() エントリポイントです。
• @cloudcare/electron-native-adapter/preload/standalone：アプリに既存の Preload がない場合に直接使用します。
• @cloudcare/electron-native-adapter/preload/install：アプリに既存の Preload がある場合、バンドラーでアプリ側 Preload にマージします。

Adapter のソースコードをコピーしたり、npm パッケージ内で exports によって宣言されていない内部ファイルを参照したりしないでください。

上記の vcpkg コマンドは x64 を例としています。vcpkg のツールディレクトリを手動で使用する場合は、以下の sdkDirectory を native.directory に渡します。デフォルトの npm ダウンロードフローでは、この設定は不要です：

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",
    );

開発ディレクトリの相対的な階層は、アプリケーションの構成に合わせて調整してください。現在の作業ディレクトリに依存したり、開発マシンの絶対パスをハードコードしたりしないでください。

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 electron = require("electron");
const { bootstrap } = require("@cloudcare/electron-native-adapter");

const rumBridge = await bootstrap({
  electron,
  native: {
    mode: "external",
    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 を収集する場合は、Native のカスタムログも有効にし、logging_enabled を 1 に設定する必要があります。

フルモード¶

アプリ自体が Electron の場合、Main Process が Bridge EXE を起動し、管理します。app.whenReady() の完了後、レンダラーページを読み込む前に、以下の初期化を実行します：

const electron = require("electron");
const path = require("node:path");
const { bootstrap } = require("@cloudcare/electron-native-adapter");

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

DataWay 経由でアップロードする場合は、datakitUrl を datawayUrl と clientToken に置き換えます。applicationId、service、environment、version は必須で、DataKit または DataWay のアドレスも指定する必要があります。

Native RUM、Log、Replay、Trace のサンプリングレートは、いずれも 0 から 1 の範囲で、デフォルトはすべて 1 です。loggingEnabled、replayEnabled、traceEnabled、debug はデフォルトで無効です。サンプルでは明示的にログを有効にしています。replayPrivacy は allow、mask-user-input、mask に対応しており、デフォルトは mask です。

その他のオプション設定：

アプリ終了前には、rumBridge.stop() の完了を待つ必要があります。例：

let stopping = false;
electron.app.on("before-quit", (event) => {
  event.preventDefault();
  if (stopping) return;
  stopping = true;
  rumBridge.stop().then(() => electron.app.exit(0), (error) => {
    console.error(error);
    electron.app.exit(1);
  });
});

bootstrap() は統一された Client を返し、capabilities、attachWindow()、detachWindow()、updateWindow()、transportState、冪等な stop() を提供します。transportState は、書き込み可能状態、バックプレッシャー、転送エラーの確認に使用します。startFullMode() と connectMixedMode() は旧バージョン互換のエントリポイントとしてのみ残されており、新規導入では統一して bootstrap() を使用してください。

Adapter はデフォルトで enableAppLaunch が有効になっており、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 = require.resolve(
  "@cloudcare/electron-native-adapter/preload/standalone",
);

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

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

アプリに既存の Preload がある場合は、@cloudcare/electron-native-adapter/preload/install を webpack、esbuild などのバンドラーのビルド依存関係として追加し、アプリ側 Preload 内で 1 回呼び出します：

const {
  installElectronRumPreload,
} = require("@cloudcare/electron-native-adapter/preload/install");

installElectronRumPreload();

sandbox: true を有効にする場合、最終的な Preload 成果物は、webPreferences.preload から直接ロードできる自己完結型バンドルである必要があります。たとえば esbuild を使用し、Electron をランタイムの外部依存として保持できます：

esbuild src/preload.cjs --bundle --platform=node --format=cjs --external:electron --outfile=dist/preload.cjs

収集が不要なページには Guance Preload を読み込まず、attachWindow() も呼び出さないでください。マルチウィンドウアプリの場合、各ウィンドウはページを読み込む前に個別に登録する必要があります。Adapter はウィンドウの破棄時に登録を自動的に解除します。返された解除関数を使用して、収集を早期に停止することもできます。

すべてのウィンドウが信頼できる場合は、bootstrap() で autoAttach: true を設定すると、既存および新規作成されたウィンドウが自動的に登録されます。デフォルト値は false です。自動登録は Preload のインストールを代替するものではありません。

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 を開始しません。ログのサンプリングは、Native の loggingSampleRate で一元的に制御することを推奨します。Browser 側で低い sessionSampleRate をさらに設定すると二重サンプリングになるため、避けてください。

リソースのパッケージング¶

フルモードでは、アプリの署名前に公開されているパッケージングヘルパー関数を呼び出し、完全なランタイムを ASAR の外にコピーしてください：

const { stageWindowsRuntime } = require(
  "@cloudcare/electron-native-adapter/packaging/windows",
);

stageWindowsRuntime({
  resourcesDirectory: "release/MyApp-win32-x64/resources",
  arch: "x64",
});

ヘルパー関数は、デフォルトで npm パッケージ内にインストール済みのランタイムを検出し、resources/native にコピーします。ターゲットディレクトリは空である必要があります。パッケージング後の managed モードは、このディレクトリを自動的に検出するため、native.directory の設定は不要です。Native EXE、DLL、manifest などのリソースは完全に保持し、app.asar には含めないでください。

クロスアーキテクチャでパッケージングする場合は、先にターゲットランタイムをインストールし、ターゲットの arch を明示的に渡します。Windows は x64、x86 / ia32、arm64 に対応しています。CLI でインストールしたランタイムは、ヘルパー関数の nativeDirectory で指定する必要があります。

vcpkg のツールディレクトリを手動で使用する場合も、electron-builder の extraResources によるコピーを継続して利用でき、前述の sdkDirectory を使用してリソースの場所を指定します：

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

フルモードでは、同じ SDK バージョンの guance_windows_electron_bridge.exe と、隣接する guance_windows_native.dll を配布する必要があります。また、アプリのパッケージングツールで @cloudcare/electron-native-adapter も同梱してください。ハイブリッドモードでは、vcpkg のツールディレクトリをコピーする必要はありません。Native DLL は引き続き C++ ホストの既存のデプロイプロセスで配布され、JavaScript Adapter は引き続き npm 依存関係として提供されます。現在の作業ディレクトリや開発マシンの絶対パスに依存してリソースを検出しないでください。

ランタイムのカスタム/オフラインインストール¶

npm インストール時に --ignore-scripts を使用した場合、または別のターゲットアーキテクチャが必要な場合は、アプリのルートディレクトリで実行します：

npx guance-electron-native --sdk-version <sdk-tag> --target <target>

Windows のターゲットは win32-x64、win32-x86、win32-arm64、macOS は darwin-universal です。<sdk-tag> には Native SDK リリースの完全なタグを使用し、vcpkg_、nuget_、v などの既存のプレフィックスを保持します。タグの下に対応するランタイムアセットが存在する必要があります。

オフラインインストールには、SDK の .tar.gz と、隣接する .tar.gz.sha256 チェックサムファイルが必要です：

npx guance-electron-native --sdk-version <sdk-tag> --target <target> --runtime-archive C:/sdk/runtime.tar.gz

CLI はランタイムをアプリのルートディレクトリにインストールします。開発時は出力ディレクトリを native.directory に渡し、パッケージング時は stageWindowsRuntime() の nativeDirectory に渡します。パッケージング後は開発ディレクトリの設定を削除し、自動的に検出される resources/native を使用します。

npm postinstall では、以下の環境変数を使用できます（PowerShell では $env:变量名 = "值" で設定します）：

アーカイブは、指定した SDK バージョンおよびアーキテクチャと一致している必要があります。オフラインの Native Runtime を提供するだけでは、npm が完全にオフラインになるわけではありません。npm パッケージとその依存関係のキャッシュも事前に準備する必要があります。プライベートソースのチェックアウトでは自動ダウンロードがスキップされるため、ローカルの file: 依存関係で結合テストを行う場合は、自分でランタイムを準備する必要があります。

統合の境界¶

• Main Process は、@cloudcare/electron-native-adapter がエクスポートするパブリックインターフェースのみを使用し、SDK 内部の IPC Channel を自ら登録しないでください。
• アプリケーションID、Client Token、DataKit/Dataway アドレス、ネイティブ Session、完全な Native 設定を Renderer に公開しないでください。
• Main Process は、信頼できる webContents のみを登録します。リモートページでは、ナビゲーション、ポップアップ、権限、許可ドメインも制限する必要があります。
• フルモードでは native.settings で Native Trace を設定し、ハイブリッドモードではホスト側で設定します。Adapter は Renderer に Trace 設定を注入せず、ページリクエストに Trace ヘッダーを自動的に追加することもありません。
• Renderer の JavaScript Error と Long Task は Browser RUM が収集します。unresponsive、render-process-gone、Main Process のクラッシュは Bridge が自動的に報告しないため、必要に応じて Electron の crashReporter や他の Crashpad サービスを個別に導入してください。

統合の検証¶

1. Renderer の DevTools Network で、RUM または Log の直接送信リクエストがないことを確認します。
2. View、Action、Resource、Error、Long Task と 1 件の Browser Log をトリガーし、コンソールでデータを確認します。
3. データが Native 設定のアプリケーションID、Session 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 Native Adapter Consumer Acceptance と Electron Sample を参照して、受け入れテストを実施できます。ローカルでの結合テストには npm の file: 依存関係を使用でき、本番アプリではリリースパッケージを使用し、アプリの lockfile で実際にインストールするバージョンを管理します。