Electron の構成とライフサイクル¶

このドキュメントは、Windows および macOS Native Bridge に共通の設定について説明します。初回導入時は managed クイックスタート を使用します。モードの選択は アプリ接続 を参照してください。プラットフォームホストの初期化、ランタイムのインストール、パッケージングについては、引き続き Windows と macOS をそれぞれ参照してください。

Main の設定¶

managed モードでは、bootstrap() の native.settings でアプリケーションおよびアップロードのパラメーターを設定します。external モードでは、ネイティブホストが Native SDK を設定するため、native.settings は渡しません。

Windows では 0.1 などの小数精度を保持できます。デフォルトで同梱される macOS Native Runtime は整数パーセントを使用するため、有効化した収集機能で新しいフィールドに小数を渡すと、Adapter はエラーを報告し、四捨五入は行いません。カスタム macOS Runtime の小数サンプリングのサポートはその実際の能力に依存します。通常のサンプリングと Replay はそれぞれ確認してください。古いサンプリングフィールドは Adapter 0.1.0-alpha.4 以降で非推奨となりましたが、従来の単位および既存の macOS の丸め動作とは引き続き互換性があります。同じ設定で新旧両方のフィールドを設定した場合は、新しいフィールドが優先されます（明示的な 0 の設定を含みます）。

macOS で実際に報告されるアプリケーションバージョンは、アプリのパッケージ情報によって決まります。traceEnabled は Native Trace を設定するだけで、Renderer のリクエストに Trace ヘッダーを自動的に注入しません。

ユーザー関連付けとグローバル属性は、Native SDK の機能によって一元管理されます。Windows のカスタムタグ と Apple SDK のカスタムタグ を参照してください。Adapter Client は、Browser の setUser() に相当するパブリックなユーザー関連付けインターフェースを提供しません。Adapter の内部モジュールを参照して Native の状態を変更しないでください。

Preload¶

npm パッケージの公開エントリポイントのみを使用してください。Main は @cloudcare/electron-native-adapter を使用します。業務用の Preload がない場合は、クイックスタート の preload/standalone を使用します。既存の Preload がある場合は、インストール関数を一度呼び出します：

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

installElectronRumPreload();

contextIsolation: true、nodeIntegration: false、sandbox: true を維持してください。サンドボックス化された Preload では、通常の Node.js の require() で npm パッケージを直接読み込むことはできません。アプリの bundler を使用して上記のコードとその依存関係をバンドルし、electron を外部依存として保持する必要があります。たとえば、esbuild がインストール済みのプロジェクトでは、次のコマンドで実行できます：

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

webPreferences.preload には、生成されたファイルの絶対パスを指定します。スタンドアロン Preload はサンドボックスでそのまま使用できるため、ブリッジのインストールを重複して行う必要はありません。Adapter のソースコードをコピーしたり、公開されていない internal/、core/、platform/ ファイルを直接参照したりしないでください。

ウィンドウ管理¶

収集が必要な各ウィンドウは Preload を読み込み、ページを読み込む前に登録する必要があります。autoAttach はデフォルトで false です。true に設定すると、既存およびそれ以降に作成されたウィンドウが登録されます。これは、すべてのウィンドウが信頼でき、収集が必要なアプリケーションに適していますが、Preload の代わりにはなりません。

指定したウィンドウのみを監視する場合は、bootstrap() で autoAttach: false のままにし、そのウィンドウを登録します：

// client は bootstrap() の戻り値、window は Preload が設定された BrowserWindow です。
const detach = client.attachWindow(window);
await window.loadFile("index.html");
// 収集を途中で停止する必要がある場合は、detach() または client.detachWindow(window) を呼び出します。

各ウィンドウは個別に登録します。リロードやナビゲーションで再登録する必要はありません。ウィンドウが破棄されると、Adapter は自動的に登録を解除します。信頼できないページを含むアプリケーションでは、対象のウィンドウにのみ Preload を読み込み、リモートページのナビゲーション、ポップアップ、権限、許可ドメインを制限してください。

Renderer¶

managed と external はどちらも クイックスタートの Renderer 初期化 を共通で使用します。各ページは、Bridge の準備が完了した後に Browser RUM を初期化します。実際のアプリケーション ID、Session、サンプリング、アップロードは、引き続き Native SDK によって管理されます。Bridge が存在してもデータが必ずしも届くとは限りません。Main の転送エラーとサーバー側の受信結果も確認する必要があります。

ページログ¶

まず Native のログ機能を有効にします。managed モードでは loggingEnabled: true を設定します。external モードでは Windows ホスト または macOS Logger に従って設定します。メインプロセスは client.capabilities.log で実際の機能を確認し、その機能が有効なページでのみ Browser Logs を初期化します。この状態を業務用 Preload 経由で伝える場合は、ブール値のみを公開してください。

@cloudcare/browser-logs をインストールし（Bridge 連携には 3.3.6 以降が必要）、RUM Bridge の連携が完了した Renderer で次のように使用します：

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

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

Browser 側では 100% を維持し、実際のログサンプリングは Native が制御します。Native のログ機能を無効にしている場合は、ページ側で Logs を単独で初期化して予備のアップロード経路としないでください。

Session Replay¶

Replay はデフォルトで無効です。Native SDK の設定、対応するコンポーネント、Bridge の実際の機能という要件をすべて満たす必要があります。まず Windows のオプションの Replay ランタイム または macOS の Replay 設定 を完了してから、datafluxRum.init() の後に機能を確認します：

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

records は Native がリプレイ機能を提供することを示しますが、現在の Session が必ずサンプリング対象になることを意味するわけではありません。Browser の独立した録画フローをそのまま流用して Replay を強制的に有効にしないでください。メインプロセスでも client.capabilities.replay を確認できます。コンポーネントの欠落、無効化・有効化後の検証は、プラットフォームの説明に従って実行してください。

ライフサイクルと診断¶

bootstrap() は Client を返し、capabilities、attachWindow()、detachWindow()、updateWindow()、transportState、および冪等な stop() を提供します。onError を使用して、非同期の転送エラーとウィンドウ処理エラーを受け取ります。transportState は、書き込み可能な状態、バックプレッシャー、転送失敗を確認するために使用します。

正常終了時は stop() を待つ必要があります。完全な非同期終了処理については、クイックスタートの Main の例 を参照してください。収集の停止は、「すべてのオフラインデータがアップロード済みである」ことの確認にはなりません。Windows の接続タイムアウト、Bridge 出力、起動アクションなどのパラメーターは、プラットフォーム設定 を参照してください。macOS には Windows のような自動起動アクションはありません。混合モードのリプレイウィンドウの可視性の境界については、macOS の Replay を参照してください。