Electron アプリケーション導入ガイド¶

Electron アプリケーションは、main process と renderer process で構成されます。RUM SDK はブラウザ環境で動作するため、renderer process でのみ初期化し、ウィンドウ内のページアクセス、リソース、リクエスト、エラー、ユーザー行動データを収集します。

本ドキュメントでは、SDK の初期化パラメータを使用して、Electron アプリケーションの導入方法を説明します。

導入の原則¶

• renderer process でのみ RUM SDK を初期化し、main process では初期化しないでください。
• 監視対象となる各 BrowserWindow、BrowserView、webview に対応する renderer ページごとに導入が必要です。
• ページが file:// で読み込まれる場合は、必ず sessionPersistence: 'local-storage' を使用し、利用不可または不安定な cookie に依存しないようにしてください。
• ページが https:// で読み込まれる場合は、デフォルトの cookie セッション戦略を引き続き使用できます。また、一律に local-storage を使用することも可能ですが、RUM と Logs SDK のセッション戦略を一致させる必要があります。
• 同じ Electron アプリケーションでローカルの file:// ページとリモートの http(s):// ページを同時に使用する場合、ブラウザの同一オリジンポリシーによって分離され、通常は異なる session が生成されます。

推奨される導入方法¶

NPM 導入¶

Webpack、Vite、Rollup などで renderer コードをビルドする Electron アプリケーションに適しています。

npm install @cloudcare/browser-rum @cloudcare/browser-core

renderer のエントリファイルで初期化します：

import { datafluxRum } from '@cloudcare/browser-rum'

datafluxRum.init({
  applicationId: '<アプリケーション ID>',

  // Public DataWay 経由で接続
  clientToken: '<clientToken>',
  site: '<Public DataWay アドレス>',

  // DataKit 経由で接続する場合は、datakitOrigin を設定
  // datakitOrigin: '<DataKit ドメインまたは IP>',

  service: 'electron-renderer',
  env: 'production',
  version: '<アプリケーションバージョン>',
  sessionSampleRate: 100,
  trackUserInteractions: true,

  // file:// ページでは必須
  sessionPersistence: 'local-storage'
})

Session Replay が必要な場合：

datafluxRum.startSessionReplayRecording()

CDN 導入¶

renderer の HTML を直接管理するアプリケーションに適しています。デスクトップアプリケーションがオフラインや弱いネットワーク環境でリモート CDN に依存することを避けるために、SDK ファイルをアプリケーションの静的リソースとして一緒にパッケージ化することを推奨します。

<script src="./vendor/dataflux-rum.js" type="text/javascript"></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: '<アプリケーション ID>',
      clientToken: '<clientToken>',
      site: '<Public DataWay アドレス>',
      service: 'electron-renderer',
      env: 'production',
      version: window.__APP_VERSION__,
      sessionSampleRate: 100,
      trackUserInteractions: true,
      sessionPersistence: 'local-storage'
    })
</script>

renderer ページが常に https:// で読み込まれ、cookie が利用可能な場合は、sessionPersistence を設定しなくても構いません。

main process の例¶

main process はウィンドウの作成を担当し、RUM SDK のインポートや初期化は必要ありません。バージョンやチャネルなどの必要な情報のみを renderer に渡すことを推奨します。

const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false
    }
  })

  win.loadFile('index.html')
}

app.whenReady().then(createWindow)

preload.js では、安全で読み取り専用のアプリケーション情報のみを公開できます：

const { contextBridge } = require('electron')
const { version } = require('./package.json')

contextBridge.exposeInMainWorld('electronAppInfo', {
  version
})

renderer で読み取り、RUM 設定に書き込みます：

datafluxRum.init({
  applicationId: '<アプリケーション ID>',
  clientToken: '<clientToken>',
  site: '<Public DataWay アドレス>',
  service: 'desktop-app',
  env: 'production',
  version: window.electronAppInfo.version,
  sessionSampleRate: 100,
  trackUserInteractions: true,
  sessionPersistence: 'local-storage'
})

マルチウィンドウ導入¶

アプリケーションが複数のウィンドウを同時に開く場合：

• 各ウィンドウ内の renderer ページで RUM SDK を初期化する必要があります。
• sessionPersistence: 'local-storage' を使用する場合、複数ウィンドウ間の localStorage の同期にはごく短い遅延が発生する可能性があります。
• 初期化直後に大量のウィンドウを同時に作成すると、短時間の一時的な session が生成される可能性があります。ウィンドウの作成と初期化の間に少なくとも数十ミリ秒の間隔を空けるか、業務の順序に従ってウィンドウを1つずつ作成することを推奨します。

ローカルページとリモートページ¶

Electron アプリケーションでは、一般的に2種類のページソースがあります：

アプリケーションがローカルのランディングページからリモートサイトに遷移する場合、RUM では2つの異なるセッションとして表示されることを想定してください。user.id、service、env、version フィールドを統一して関連分析を行うことを推奨します。

datafluxRum.setUser({
  id: currentUserId,
  name: currentUserName
})

API リクエストと分散型トレーシング¶

renderer 内の fetch および XMLHttpRequest は、ブラウザ SDK のロジックに従って自動的に収集されます。バックエンド API に Trace Header を注入する必要がある場合は、allowedTracingUrls を設定する必要があります：

NPM + TypeScript で導入する場合、traceType には browser-core パッケージからインポートした TraceType 列挙型を使用します：

import { TraceType } from '@cloudcare/browser-core'
import { datafluxRum } from '@cloudcare/browser-rum'

datafluxRum.init({
  applicationId: '<アプリケーション ID>',
  clientToken: '<clientToken>',
  site: '<Public DataWay アドレス>',
  service: 'desktop-app',
  env: 'production',
  version: window.electronAppInfo.version,
  sessionPersistence: 'local-storage',
  allowedTracingUrls: [
    'https://api.example.com',
    /https:\/\/.*\.internal-api\.example\.com/
  ],
  traceType: TraceType.DDTRACE
})

CDN 導入ではモジュールのインポートがないため、このタイプを明示的に指定する場合はランタイム値 'ddtrace' を使用します。設定しない場合も、デフォルトでこの値が使用されます。

file:// ページのアドレスを allowedTracingUrls に含めないでください。この設定はバックエンド API リクエストを照合するためのものであり、renderer ページ自体を対象とするものではありません。

エラーと SourceMap¶

Electron のローカルページのエラースタックトレースは、多くの場合 file:// で始まります。サーバー側では、公開 URL のように SourceMap と直接照合できない可能性があります。以下の点を推奨します：

• service、env、version とビルド成果物のバージョンを一致させてください。
• renderer の成果物に対して SourceMap を生成し、リリースバージョンごとに保存してください。
• ローカルファイルパスを書き換える必要がある場合は、beforeSend でビジネスコンテキストを追加し、後で検索しやすくしてください。

datafluxRum.init({
  // ...
  beforeSend: (event) => {
    if (event.type === 'error') {
      event.context = {
        ...event.context,
        electron: true,
        rendererUrl: window.location.href
      }
    }
    return true
  }
})

CSP と Worker¶

Session Replay、compressIntakeRequests、またはキャンバス録画を有効にすると、SDK が Worker を使用する場合があります。厳格な CSP を設定している Electron アプリケーションでは、対応する Worker のオリジンを許可する必要があります。

デフォルトのインライン Worker には、通常、以下が必要です：

worker-src blob:;

blob: を許可しない場合は、Worker ファイルをアプリケーションの静的リソースとしてパッケージ化し、同一オリジンのアドレスを設定してください：

datafluxRum.init({
  // ...
  workerUrl: './worker.js',
  replayCanvasWorkerUrl: './canvas-worker.js'
})

@cloudcare/browser-rum-slim を使用する場合、このパッケージには Session Replay と compressIntakeRequests の圧縮機能が含まれていないため、通常はこれらの機能のために Worker を設定する必要はありません。

セキュリティに関する推奨事項¶

• main process で RUM token やその他の機密設定の書き込みインターフェースを公開しないでください。
• preload では、アプリケーションバージョン、チャネル、ビルド番号など、必要な読み取り専用情報のみを公開してください。
• contextIsolation: true および nodeIntegration: false を維持してください。
• beforeSend でローカルファイルの絶対パス、ユーザー名ディレクトリ、またはその他の機密情報を送信しないでください。
• ユーザー入力、ファイル名、パスなどのフィールドは、カスタムコンテキストに書き込む前にマスキングしてください。

検証方法¶

導入後、次の順序で検証できます：

1. Electron アプリケーションの対象ウィンドウを開きます。
2. DevTools の Network タブで RUM の送信リクエストを確認します。
3. ページアクセス、ボタンクリック、API リクエスト、フロントエンドエラーを1回ずつ発生させます。
4. view、action、resource、error データが Guance に取り込まれていることを確認します。
5. 同じユーザーが複数ウィンドウ、またはローカル/リモートページを切り替えた際の session が期待通りであることを確認します。

ローカルでデバッグする場合は、一時的に beforeSend でイベントタイプを出力することもできます：

datafluxRum.init({
  // ...
  beforeSend: (event) => {
    console.log('[RUM]', event.type, event)
    return true
  }
})

よくある質問¶

main process にデータがないのはなぜですか？¶

RUM SDK はブラウザ側の SDK であり、renderer process 内のページ動作のみを収集します。main process でのクラッシュ、IPC、ファイルシステム、ネイティブモジュールのエラーは、アプリケーション独自のログまたはクラッシュ収集機能で処理する必要があります。

file:// ページに session がないのはなぜですか？¶

通常は sessionPersistence: 'local-storage' が設定されていないか、renderer ページが実行されている環境で localStorage が無効になっていることが原因です。まず、この設定と localStorage の可用性を確認してください。

ローカルページからリモートページに遷移すると session が変わるのはなぜですか？¶

file:// と https:// は異なるオリジンに属するため、ブラウザは同じ cookie または localStorage を共有しません。setUser() で安定したユーザー ID を設定し、分析時にユーザー単位で関連付けることを推奨します。

複数ウィンドウで短い session が表示されるのはなぜですか？¶

複数ウィンドウを同時に初期化する場合、ウィンドウ間での localStorage の同期にごく短い遅延が発生する可能性があります。同一瞬間に多数のウィンドウを作成して初期化することは避け、ウィンドウの作成間に短い間隔を空けることを推奨します。

参考資料¶

• Electron: Process Model