コンテンツにスキップ

Electron クイックスタート

この記事は、アプリケーション自体が Electron であり、Adapter が Native SDK を管理するフルモード（managed）を対象としています。Browser 単独での報告のみが必要な場合や、既存のネイティブホストがある場合は、まずアクセス方式の選択をお読みください。

準備とインストール

対象プラットフォームのネイティブ RUM アプリケーション ID と、利用可能な DataKit アドレス、または DataWay アドレスと Client Token を準備します。これらは Main Process で設定し、Native SDK が Session、サンプリング、ユーザー、グローバルコンテキスト、永続化、アップロードを管理します。Renderer のプレースホルダー設定は、独立した Web アプリケーションの作成には使用されず、アップロードの役割も担いません。

インストールには Node.js 18+ が必要です。Windows では、ターゲットアーキテクチャに一致する Microsoft Visual C++ v14 Redistributable と Windows Universal CRT も必要です。Electron とプラットフォームの要件はサポート範囲を参照してください。

Electron Native Adapter バージョン

既存の Electron プロジェクトにインストールします：

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

postinstall は、現在のプラットフォームに対応する Native Runtime をダウンロードして検証します。ローカルでのコンパイルは不要です。インストールスクリプトはそのまま残してください。この例では native.directory は設定しません。オフライン、カスタムランタイム、ネイティブホストへのアクセスについては、プラットフォーム別のドキュメントを参照してください。初回アクセス時に vcpkg をインストールする必要はありません。

Main：初期化とウィンドウ登録

以下のコードを、アプリケーションの CommonJS メインプロセスエントリ（例：main.cjs）に統合します。Electron の準備完了と bootstrap() の完了を待ってから、ウィンドウを作成して読み込みます。

const electron = require("electron");
const { app, BrowserWindow } = electron;
const { bootstrap } = require("@cloudcare/electron-native-adapter");

let client;
let stopping = false;
let stopped = false;

// Electron は非同期の終了コールバックを自動的には待たない。
app.on("before-quit", (event) => {
  if (!client || stopped) return;
  event.preventDefault();
  if (stopping) return;
  stopping = true;
  client.stop().catch(console.error).finally(() => {
    stopped = true;
    app.quit();
  });
});

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: "managed",
      settings: {
        applicationId: "<RUM 应用 ID>",
        datakitUrl: "http://127.0.0.1:9529",
        service: "electron-desktop",
        environment: "prod",
        version: app.getVersion(),
      },
    },
    autoAttach: true,
    onError: console.error,
  });

  const window = new BrowserWindow({
    webPreferences: {
      preload: require.resolve(
        "@cloudcare/electron-native-adapter/preload/standalone",
      ),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });
  await window.loadFile("index.html");
}).catch((error) => {
  console.error(error);
  app.quit();
});

app.on("window-all-closed", () => app.quit());

この例ではすべてのウィンドウが信頼できるため、autoAttach: true を使用します。一部のウィンドウのみを監視する場合は、手動ウィンドウ登録を使用してください。index.html は、アプリケーションの実際のビルドで生成されるページパスに置き換えてください。

DataWay を使用する場合は、datakitUrl を datawayUrl と clientToken に置き換え、実際の認証情報は Main でのみ設定します。macOS で実際に報告されるアプリケーションバージョンは、アプリケーションのパッケージ情報によって決まります。

Preload：ページブリッジの確立

上記の preload/standalone によって window.FTWebViewJavascriptBridge がインストールされるため、追加の Preload ファイルを作成する必要はありません。これは Browser RUM の初期化前に実行される必要があります。アプリケーションに既存のビジネス用 Preload がある場合は、Preload の統合に従ってインストール関数を統合し、単一のファイルとしてパッケージングしてください。

Renderer：ページデータ収集の初期化

以下のコードを、既存のフロントエンドビルドツールで処理される Renderer エントリに配置し、index.html がそのエントリのビルド成果物を読み込むようにしてください。npm のベアモジュールインポートを含むソースファイルを、サンドボックスページのスクリプトとして直接読み込まないでください。

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

if (typeof window.FTWebViewJavascriptBridge?.sendEvent !== "function") {
  throw new Error("Electron Native Bridge 尚未就绪");
}

datafluxRum.init({
  applicationId: "native-bridge",
  datakitOrigin: "http://127.0.0.1",
  service: "electron-renderer",
  env: "prod",
  sessionSampleRate: 100,
  trackUserInteractions: true,
});

applicationId と datakitOrigin はプレースホルダー値のままで問題ありません。Bridge が有効な場合、Browser SDK はイベントを Native に渡し、このアドレスに RUM リクエストを送信しません。Bridge が未準備の場合は、まず Preload とウィンドウ登録を修正してください。チェックを削除して初期化を続行したり、Browser 単独報告の実際のアプリケーション ID、Token、セッション永続化設定を混在させたりしないでください。

収集対象の各ページで初期化を 1 回実行します。ページが更新された後は、そのページのエントリによって再初期化されます。実際のサンプリングは Native が制御するため、Browser は 100% のまま維持し、サンプリングレートが二重に低下しないようにしてください。

終了時のクリーンアップ

Main の例では、before-quit で client.stop() を待機し、クリーンアップが完了してから終了を続行します。Windows では Adapter が起動した Bridge EXE を終了し、macOS では Adapter が初期化した Native SDK を終了する必要があります。プロセスを直接終了する方法で通常の終了を代替しないでください。stop() が完了しても、オフラインキューがすべてサーバーに配信されたことを意味するわけではありません。

報告の検証

  1. 開発時実行：プロジェクトの既存の起動コマンドでアプリケーションを実行し、Main に初期化エラーがないこと、Renderer に Bridge が存在すること、Network に Browser RUM の直接送信リクエストがないことを確認します。

  2. ページイベント：ページにアクセスし、ボタンをクリックして、リクエストを 1 回送信し、テストエラーをトリガーします。Guanceで、View、Action、Resource、Error が Native 設定のアプリケーション ID を使用していることを確認します。Long Task は、収集しきい値を超えるタスクをトリガーする必要があります。

  3. 複数ウィンドウ：2 つ目のウィンドウを作成し、同じ Preload を読み込んでそのページで Browser RUM を初期化し、両方のウィンドウにデータがあることを確認します。Native が Session を切り替えていない条件下でセッションの関連付けを確認します。手動登録を使用する場合は、未登録ウィンドウが Bridge データを生成しないことを確認します。

  4. 終了：アプリケーションを正常に閉じ、client.stop() が完了し、クリーンアップエラーがないことを確認します。Windows では、このアプリケーションが起動した Bridge EXE が終了していることを確認します。

  5. パッケージング実行：Windows パッケージングまたは macOS パッケージングと署名に従って、完全なランタイムを ASAR の外に配置した上で、パッケージング成果物を実行し、上記の確認を繰り返します。検証が開発マシンの絶対パスに依存しないことを確認します。

アクセスが完了したら、共通設定に従って、サンプリング、ウィンドウ、オプションの収集機能を調整します。

フィードバック

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