macOS Electron モニタリング¶

このページでは、macOS ネイティブホスト、ランタイム、Replay、パッケージ署名に関する説明を記載します。初回の組み込みは Electron アプリの組み込み から方式を選択してください。アプリの主体が Electron の場合は、先に managed クイックスタート を完了してください。

macOS SDK は Guance Electron Native Adapter を介して Electron に接続します。Renderer 内の Browser RUM と Browser Logs がページビュー、ユーザー操作、リクエスト、エラー、Long Task、ページログを収集し、Electron メインプロセスがデータを macOS Native SDK に渡して、ネイティブ RUM アプリ、セッション、サンプリング、アップロードを一元管理します。セッションリプレイが必要な場合は、下文に従って Native SDK とページレコーディングの両方を設定してください。

アプリの構成に応じて 1 つのモードを選択してください。同じ Electron プロセスでは 1 つのモードのみを使用します：

2 つのモードは、同じ Preload、ウィンドウ登録、Renderer 初期化方法を共用します。Renderer には実際の RUM アプリ ID、アップロード先、Client Token を設定しません。モードを選択したら、Preload を設定してページ SDK を初期化します。Electron ページを独立した Web アプリとしてモニタリングするだけでよい場合は、Web RUM の Electron 組み込み を参照してください。

データフローは次のとおりです：

全量モード（managed）
Electron Renderer
  Browser SDK -> 安全な Preload -> Electron メインプロセス
                                      |
                                      v
                      Node Addon（Native SDK 内蔵）
                                      |
                                      v
                                     アップロード

混合モード（external）
Electron Renderer
  Browser SDK -> 安全な Preload -> Electron メインプロセス
                                      |
                                      | 認証済み Unix Domain Socket
                                      v
                         macOS ネイティブメインプログラム
                         Native SDK -> アップロード

Electron への統合¶

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

• Adapter と Native ランタイムのインストールには Node.js 18 以上が必要で、npm Registry と Native SDK の GitHub Release にアクセスできる必要があります。オフライン環境では、npm パッケージ、依存関係、Native ランタイムのアーカイブを事前に用意してください。
• 全量モードではプリコンパイル済みの Universal ランタイムを使用するため、インストール時に Native SDK をコンパイルしません。そのために Git、Swift、Xcode Command Line Tools をインストールする必要はありません。アプリのパッケージング、署名、公証には引き続き対応する macOS ツールチェーンが必要です。
• 混合モードでは、先に macOS ネイティブメインプログラムに Native SDK を組み込む必要があります。後述の configureElectronProcess による組み込み方法は Native SDK 1.6.8-alpha.7 以降で利用できます。ネイティブメインプログラムへの統合 を参照してください。

Guance Electron Native Adapter は Electron 22.x（22.3.27 以上）および 43.x をサポートします。

全量モードでは 共通クイックスタート に従って依存関係をインストールし、Main、Preload、Renderer を組み込みます。インストール時に、対応する macOS ランタイムが自動的にダウンロードされるため、ローカルでのコンパイルは不要です。

混合モードのみを使用する場合、Native SDK はネイティブメインプログラムが提供するため、Adapter のインストール時には不要なランタイムのダウンロードをスキップします：

GUANCE_NATIVE_SKIP_DOWNLOAD=1 npm install @cloudcare/electron-native-adapter@alpha

ページの依存関係と初期化は 共通 Renderer の組み込み を参照してください。オプションのログは、先に後述の ネイティブ Logger 設定 を完了してください。

全量モード Native ランタイムの指定またはオフラインインストール¶

npm による自動インストールのランタイムを使用する場合、開発段階では native.directory を設定する必要はありません。Adapter は自身のインストールディレクトリからランタイムを探します。npm パッケージと Native SDK のバージョン番号は互いに独立しており、同梱される Native SDK のバージョンは npm パッケージで固定されます。両者のバージョン番号が一致している必要はありません。

別の Native SDK バージョンを指定する場合は、Electron アプリプロジェクトのルートディレクトリで次のコマンドを実行し、<SDK_VERSION> を Electron ランタイムアセットを含む Native SDK の Release タグに置き換えてください：

npx guance-electron-native --sdk-version '<SDK_VERSION>'

このコマンドは、arm64 と x86_64 の両方を含むプリコンパイル済みの Universal ランタイムをダウンロードします。単一アーキテクチャ向けのソースビルドオプションは提供されません。インストーラーは、アーカイブ、SDK バージョン、アーキテクチャ、ファイルハッシュを検証します。

オフラインインストールでは、同じ Release 内の guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz と、それと同じ名前の .sha256 ファイルを事前に用意し、両方を同じディレクトリに配置してください：

npx guance-electron-native --sdk-version '<SDK_VERSION>' \
  --runtime-archive '/absolute/path/guance-electron-runtime-<SDK_VERSION>-darwin-universal.tar.gz'

オフラインコマンドを実行する前に、Adapter とその npm 依存関係をインストールしておく必要があります。そうしないと、npx 自体が npm にアクセスする可能性があります。また、npm インストール時にローカルのランタイムアーカイブを渡すこともできます：

GUANCE_NATIVE_RUNTIME_ARCHIVE='/absolute/path/runtime.tar.gz' \
  npm install @cloudcare/electron-native-adapter@alpha

ローカルのアーカイブがネットワークダウンロードよりも優先されます。そのバージョンは、今回のインストールで選択した Native SDK のバージョンと一致している必要があります。npm インストール時は GUANCE_NATIVE_SDK_VERSION で同梱バージョンを上書きできます。明示的な CLI インストールでは --sdk-version を使用します。バージョンを変更したら、アプリを実行してデータが正常に送信されることを確認してください。

npm が自動インストールしたランタイムは node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime に配置されます。明示的な CLI インストールではアプリプロジェクトの .cloudcare/native/darwin/runtime に出力されるため、この場合は native.directory をそのディレクトリの絶対パスに設定する必要があります。プロジェクト内の .cloudcare/ を Git の無視ルールに追加することをお勧めします。

パッケージング時は、完全な runtime ディレクトリをアプリのリソースディレクトリにコピーしてください。具体的な設定は パッケージングリソース を参照してください。

Native Bridge の初期化¶

全量モード¶

macOS managed モードでは、Electron メインプロセスが Node Addon 経由で Native SDK を初期化します。完全な例は managed クイックスタート を参照し、フィールドとサンプリング単位は Main 設定 を参照してください。

macOS で実際に報告されるアプリのバージョンは、アプリのパッケージ情報によって決まります。Native SDK のサンプリング API を直接呼び出す場合は 0..100 を使用します。旧 Adapter のフィールドの 0..1 という単位と混在させないでください。

混合モード¶

混合モードでは native.mode: 'external' を使用します。先に macOS ネイティブメインプログラムで SDK を設定し、その後でネイティブメインプログラムが Electron を起動する必要があります。アプリ情報、アップロード先、収集オプションは、ネイティブメインプログラムで一元的に設定します。

ネイティブメインプログラムへの統合¶

ネイティブメインプログラムのプロジェクトで Swift Package Manager を使用して Native SDK を追加し、<SDK_VERSION> を使用する SDK のバージョン番号に置き換えてください：

.package(
    url: "https://github.com/GuanceCloud/datakit-ios.git",
    exact: "<SDK_VERSION>"
)

次の Product を macOS メインプログラムの Target に追加します：

• GuanceSDK：Native SDK
• GuanceElectronWebView：Electron のページデータを接続するために使用
• GuanceSessionReplay：Session Replay が必要な場合のみ追加

ネイティブメインプログラムは、最初に SDK と RUM を初期化します。すでに SDK を組み込んでいるアプリは既存の初期化コードを維持し、enableTraceWebView を有効にしてください。初期化を繰り返す必要はありません：

#import <GuanceSDK/GuanceSDK.h>
#import <GuanceElectronWebView/GuanceElectronWebView.h>

FTSDKConfig *sdkConfig =
    [[FTSDKConfig alloc] initWithDatakitUrl:@"http://127.0.0.1:9529"];
[FTSDKAgent startWithConfigOptions:sdkConfig];

FTRumConfig *rumConfig =
    [[FTRumConfig alloc] initWithAppid:@"<RUM 应用 ID>"];
rumConfig.enableTraceWebView = YES;
rumConfig.enableTraceUserView = YES;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];

Session Replay が必要な場合は、Electron サブプロセスを起動する前に Native SDK の Session Replay API で初期化します。ページログも必要な場合は、この段階で ネイティブ Logger 設定 を完了してください：

#import <GuanceSessionReplay/GuanceSessionReplay.h>

FTSessionReplayConfig *replayConfig = [[FTSessionReplayConfig alloc] init];
replayConfig.sampleRate = 100;
replayConfig.textAndInputPrivacy = FTTextAndInputPrivacyLevelMaskSensitiveInputs;
[[FTRumSessionReplay sharedInstance]
    startWithSessionReplayConfig:replayConfig];

Electron サブプロセスの設定と起動¶

FTElectronBridgeServer と NSTask を作成し、サブプロセスを起動する前に configureElectronProcess:error: を呼び出します。このメソッドは Bridge を自動的に起動し、接続パラメータを指定したサブプロセスの環境変数にマージします。startWithError: を別途呼び出したり、Bridge の環境変数を手動で設定したりする必要はありません。

AppDelegate または子プロセスのライフサイクルを管理するオブジェクトに、強い参照のプロパティを宣言します：

@property (nonatomic, strong) FTElectronBridgeServer *electronBridgeServer;
@property (nonatomic, strong) NSTask *electronProcess;

前の Native SDK の設定が完了したら、次の起動コードを実行します：

self.electronBridgeServer = [[FTElectronBridgeServer alloc] init];
self.electronProcess = [[NSTask alloc] init];
self.electronProcess.executableURL =
    [NSURL fileURLWithPath:@"<Electron 可执行文件的绝对路径>"];
// アプリの構成に応じて起動パラメータを設定します。例: 開発モードでの Electron プロジェクトのパス。
// self.electronProcess.arguments = @[@"<Electron 项目的绝对路径>"];

NSError *error = nil;
if (![self.electronBridgeServer
        configureElectronProcess:self.electronProcess error:&error]) {
    [self.electronBridgeServer stop];
    // アプリ内で error を処理し、設定が成功していないサブプロセスを起動しないでください。
    return;
}

// configureElectronProcess はプロセスの設定のみを行い、Electron を自動起動しません。
if (![self.electronProcess launchAndReturnError:&error]) {
    [self.electronBridgeServer stop];
    // アプリ内で起動失敗を処理します。
    return;
}

Swift では、try bridgeServer.configureElectronProcess(process) を呼び出し、続けて try process.run() を実行します。

業務用の環境変数を渡す場合は、configureElectronProcess を呼び出す前に electronProcess.environment を設定します。SDK は既存の Bridge 以外のパラメータを保持します。設定しない場合は、NSProcessInfo.processInfo.environment を継承します。このメソッドは指定したサブプロセスの起動環境のみを変更し、ネイティブメインプログラムの環境は変更しません。起動前に繰り返し呼び出すことはできますが、既存の Bridge パラメータは現在の Bridge の値で置き換えられます。

次の接続パラメータは Native Bridge が生成または提供し、Adapter はデフォルトで Electron メインプロセスの process.env から読み取ります。ユーザーが手動で値を設定したり .env.local に書き込んだりする必要はなく、これらのパラメータを Renderer に公開しないでください：

configureElectronProcess をサポートしない旧 SDK やカスタムランチャーを使用する場合は、先に startWithError: を呼び出し、environmentByAddingToEnvironment: の戻り値を Electron の起動環境として渡すことができます。Bridge を起動するだけでは、別のプロセスの環境変数は自動的に変更されません。

Electron メインプロセスの設定¶

Electron が最初のウィンドウを作成またはナビゲートする前に、bootstrap() を使用してネイティブメインプログラムに接続します。native.settings を渡したり、接続パラメータを手動で読み取ったりする必要はありません：

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

let client

app.whenReady().then(async () => {
  client = await bootstrap({
    electron,
    native: {
      mode: 'external',
    },
    autoAttach: true,
  })

  const window = new BrowserWindow({ /* 安全な Preload を設定 */ })
  await window.loadURL('https://example.com')
})

アプリの終了¶

正常終了時は client.stop() の完了を待ちます。具体的な処理は 共通ライフサイクル を参照してください。混合モードでは Electron の接続を切断するだけで、Bridge と Native SDK の停止は引き続きネイティブメインプログラムが担当します。

Preload とウィンドウの組み込み¶

共通 Preload 設定 に従ってブリッジを読み込み、安全なウィンドウオプションを使用し、業務用 Preload を正しくパッケージングしてください。

収集対象ウィンドウの指定¶

共通ウィンドウ管理 に従って autoAttach または手動登録を選択し、収集対象の各ウィンドウは、ページを読み込む前に組み込みを完了してください。

Renderer の初期化¶

2 つのモードは クイックスタートの Renderer 初期化 を共通で使用します。プレースホルダーのパラメータを維持し、実際のアプリ、アップロード先、認証情報は Main またはネイティブホストが設定します。

ユーザー操作の収集¶

ページ上のクリックなどのユーザー操作を収集する必要がある場合は、この節の Renderer 初期化例 に従って trackUserInteractions: true を設定します。混合モードでは、ネイティブコントロールの自動操作収集は、ネイティブメインプログラムの RUM 設定 で有効にします。

ページログの収集¶

ページログを収集する必要がある場合は、まず組み込みモードに応じてログ収集を有効にします：

• 全量モード：Electron メインプロセスの native.settings で loggingEnabled: true を設定し、loggingSampleRate でサンプルレートを設定します。
• 混合モード：macOS ネイティブメインプログラムで Logger を初期化し、enableWebViewLog を有効にします。

混合モードでは、ネイティブメインプログラムが Electron を起動する前に Logger を設定します。Logger の初期化コードがすでにある場合は、次のオプションを既存の設定にマージしてください：

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.enableWebViewLog = YES;
loggerConfig.enableLinkRumData = YES;
loggerConfig.sampleRate = 100;
[[FTSDKAgent sharedInstance] startLoggerWithConfigOptions:loggerConfig];

メインプロセスは client.capabilities.log で、Native がページログを受信できるかどうかを確認できます。この機能が有効なページでのみ Browser Logs を初期化してください。業務用 Preload を介してこの状態をページに渡す場合は、必要なブール値のみを公開し、完全な Native 設定は渡さないでください。

enableWebViewLog はページログを受信するためのものです。ログをネイティブ RUM セッションに関連付ける必要がある場合は、enableLinkRumData: YES も設定し、混合モードの例に従って RUM の enableTraceWebView を有効にします。

Native の設定が完了したら、共通ページログ設定 に従って Browser Logs を初期化し、二重サンプリングを避けてください。

セッションリプレイの有効化¶

まず組み込みモードに応じてリプレイ収集を有効にします：

• 全量モード：native.settings で replayEnabled: true を設定し、必要に応じて replaySampleRate と replayPrivacy を設定します。
• 混合モード：ネイティブメインプログラムで 混合モードの例 に従って、Session Replay のサンプルレートとプライバシー保護方式を設定します。

リプレイはデフォルトでオフです。Native の設定が完了したら、共通 Replay 機能の確認 に従って、Bridge が records を返した場合にのみ録画を開始してください。この機能があっても、現在のセッションが必ずサンプリングに該当するとは限りません。

組み込みが完了すると、Guance でページビュー、ユーザー操作、対応するリプレイを確認できます。混合モードでは、同じセッション内でネイティブアプリと Electron ページのアクセスデータを確認できます。ネイティブ UI と Electron ページのリプレイはそれぞれ別に表示されます。

混合モードのページスナップショットは Browser SDK が管理し、Native Bridge がページの完全なスナップショットを逆にトリガーすることはありません。client.updateWindow(..., { visible: false }) を混合モードでの録画一時停止の手段として使用しないでください。全量モードでは、Native とページのスナップショット同期メカニズムが引き続き維持されます。

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

全量モード¶

managed モードでは、最初に Native ランタイムをインストールし、完全なディレクトリを ASAR の外にコピーする必要があります。macOS Universal の成果物には arm64 と x86_64 が含まれます。npm による自動インストールのランタイムを使用する場合、electron-builder で次の extraResources 設定によりランタイムをコピーし、.node を macOS のバイナリ署名設定に追加できます：

{
  "extraResources": [
    {
      "from": "node_modules/@cloudcare/electron-native-adapter/.cloudcare/native/darwin/runtime",
      "to": "native"
    }
  ],
  "mac": {
    "binaries": [
      "Contents/Resources/native/guance_electron.node"
    ]
  }
}

明示的な CLI インストールを使用する場合は、上記の from をアプリプロジェクトの .cloudcare/native/darwin/runtime に変更します。.node ファイルだけをコピーせず、ランタイム内のリソース Bundle も必ず一緒に配布してください。パッケージング後の Adapter は、デフォルトで process.resourcesPath 配下の native ディレクトリを優先して使用します。native.directory を明示的に設定している場合は、パッケージング後もそのディレクトリを指すようにし、開発機のパスを使い続けないでください。

アプリの既存の macOS 署名・公証フローを踏襲し、guance_electron.node も一緒に署名してください。リリース前にパッケージングしたアプリを実行し、SDK が正常に読み込まれてデータを送信できることを検証してください。

混合モード¶

混合モードでは、ネイティブメインプログラムの既存のフローに従って、Native SDK、GuanceElectronWebView、必要に応じて使用する Session Replay コンポーネントをパッケージング・署名します。Electron は通常どおりパッケージングしてください。

統合の境界¶

• ページの RUM イベントとログは、Preload とメインプロセスを経由して Native SDK に転送されます。SDK 内部の IPC Channel を独自に登録したり転送したりしないでください。
• Adapter は、登録済みウィンドウのメイン Frame のイベントのみを受け付けます。サブ Frame は独立した信頼できる入口としては扱いません。
• traceEnabled は Native SDK の Trace を設定するもので、Renderer の fetch / XHR に自動で分散型トレーシングを設定するものではありません。ページのリクエストにトレース連携が必要な場合は、Browser RUM で allowedTracingUrls と、バックエンドに合わせた traceType を別途設定してください。リポジトリの Electron サンプルを参照できます。
• 現在の macOS Adapter は、Windows 連携にある自動の launch_cold、launch_hot Action レポートを提供していません。macOS で enableAppLaunch によってこれらのイベントが生成されることを前提にしないでください。
• Renderer の JavaScript Error と Long Task は Browser RUM が収集します。Electron の unresponsive、render-process-gone は Bridge によって RUM エラーに自動変換されません。ネイティブメインプログラムのクラッシュモニタリングも Electron サブプロセスのクラッシュ収集の代わりにはならないため、アプリの要件に応じて個別に組み込む必要があります。
• リモートページのナビゲーション、ポップアップ、権限、許可するドメインを制限してください。アップロード先と認証情報は Electron メインプロセスまたはネイティブメインプログラムに設定し、ページコードには書き込まないでください。

統合の検証¶

1. アプリを起動し、メインプロセスとページのコンソールに SDK の初期化エラーがないことを確認します。Renderer DevTools の Network で、RUM やログの直接アップロードリクエストがないことを確認します。
2. ページにアクセスし、コントロールをクリックし、リクエストを送信して、エラーと Long Task を 1 つずつ発生させます。Guance で対応するデータを確認できること、およびアプリ ID が Native の設定を使用していることを確認します。ページログを有効にした後、もう 1 件ログを送信して検証します。
3. リプレイがオフの場合は、getCapabilities() に records が含まれないことを確認します。有効にしてサンプリングに該当したら録画結果を確認し、テキストと入力内容が選択したプライバシー設定に適合していることを確認します。
4. 2 つ目のウィンドウを作成し、そのウィンドウを収集できることを確認します。指定ウィンドウの収集を使用する場合、組み込んでいないウィンドウにデータがないことを確認します。
5. 混合モードでは、同じセッション内でネイティブアプリと Electron ページのアクセス記録を確認します。
6. 全量モードのアプリを終了し、client.stop() が完了することを確認します。混合モードの Electron サブプロセスを終了し、ネイティブ SDK が収集とアップロードを続行することを確認します。パッケージングしたアプリを実行し、データとリプレイが正常かどうかを再度検証します。

完全な例は、macOS SDK リポジトリの Electron 全量モードの例 と ネイティブホスト混合モードの例 を参照してください。

よくある質問¶