Electron アプリケーション導入ガイド¶
Native SDK 連携の場合は Native Bridge を使用
このページでは、Browser RUM がセッションを独自に管理し、直接アップロードする導入方法について説明します。Windows または macOS の Native SDK にセッション、サンプリング、コンテキスト、永続化、アップロードを管理させる場合は、まず Electron 導入方式の選択 をお読みください。アプリケーション本体が Electron の場合は managed クイックスタート を使用します。Native Bridge モードでは、このページの実際の applicationId、clientToken、site、sessionPersistence 設定をそのまま流用できません。
Electron アプリケーションは、main process と renderer process で構成されます。RUM SDK はブラウザ環境で動作するため、renderer process 内でのみ初期化し、ウィンドウ内のページビュー、リソース、リクエスト、エラー、ユーザー行動のデータを収集します。
本書では、現在の SDK の初期化パラメータに基づいて、Electron アプリケーションの導入方法を説明します。
導入の原則¶
- renderer process でのみ RUM SDK を初期化し、main process では初期化しないでください。
- 監視が必要な各
BrowserWindow、BrowserView、webviewに対応する renderer ページごとに、それぞれ 1 回導入する必要があります。 - ページを
file://で読み込む場合は、利用できない、または不安定な cookie に依存しないよう、必ずsessionPersistence: 'local-storage'を使用してください。 - ページを
https://で読み込む場合は、既定の cookie セッションポリシーを引き続き使用できます。local-storageに統一することもできますが、その場合は RUM と Logs SDK のセッションポリシーを一致させてください。 - 同じ Electron アプリケーション内でローカルの
file://ページとリモートのhttp(s)://ページを併用する場合、ブラウザの同一オリジンポリシーによって分離され、通常は異なるセッションが生成されます。
推奨される導入方法¶
NPM で導入¶
Webpack、Vite、Rollup などで renderer コードをビルドしている Electron アプリケーションに適しています。
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 が必要な場合:
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 同期にごく短い遅延が生じることがあります。- 初期化直後に多数のウィンドウを同時に作成すると、非常に短い一時的なセッションが発生する可能性があります。ウィンドウの作成と初期化の間に数十ミリ秒以上の間隔を空けるか、業務の順序に応じて 1 つずつウィンドウを作成することをお勧めします。
ローカルページとリモートページ¶
Electron アプリケーションでは、ページの提供元として次の 2 種類が一般的です。
| ページの提供元 | 推奨設定 | 説明 |
|---|---|---|
file:// のローカルページ |
sessionPersistence: 'local-storage' |
cookie は信頼できないため、localStorage でセッションを保存する必要があります。 |
https:// のリモートページ |
デフォルトの cookie または local-storage |
デフォルトの cookie を使用する場合は、ページのドメインとセキュリティポリシーで cookie の書き込みが許可されている必要があります。 |
file:// と https:// の混在 |
それぞれ導入してそれぞれ分析 | 同一オリジンポリシーの影響により、ローカルページとリモートページは通常、同じセッションを共有しません。 |
アプリがローカルのランディングページからリモートサイトへ遷移する場合、RUM 上では 2 つの異なるセッションとして表示されることを想定してください。統一された user.id、service、env、version フィールドを使って関連付けて分析することをお勧めします。
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 に指定しないでください。この設定は renderer ページ自体ではなく、バックエンド API リクエストを照合するためのものです。
エラーと 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、または canvas レコーディングを有効にすると、SDK が Worker を使用する場合があります。Electron アプリケーションで厳格な CSP を設定している場合は、該当する Worker のオリジンを許可する必要があります。
デフォルトのインライン Worker では通常、次の設定が必要です:
blob: を許可しない場合は、worker ファイルをアプリの静的リソースとしてバンドルし、同一オリジンの URL を設定してください:
@cloudcare/browser-rum-slim を使用する場合、このパッケージには Session Replay と compressIntakeRequests の圧縮機能が含まれていないため、通常はこれら 2 つのために worker を設定する必要はありません。
セキュリティに関する推奨事項¶
- main process で RUM token やその他の機密設定を書き込むインターフェースを公開しないでください。
preloadでは、アプリのバージョン、チャネル、ビルド番号など、必要な読み取り専用情報のみを公開します。contextIsolation: trueとnodeIntegration: falseを維持してください。beforeSendでローカルファイルの絶対パス、ユーザー名ディレクトリ、その他の機密情報を送信しないでください。- ユーザー入力、ファイル名、パスなどのフィールドはマスキングしてからカスタムコンテキストに書き込みます。
動作確認方法¶
導入後、次の順序で確認できます。
- Electron アプリケーションの対象ウィンドウを開きます。
- DevTools の Network で RUM の送信リクエストが存在することを確認します。
- ページビュー、ボタンクリック、API リクエスト、フロントエンドエラーを 1 回ずつ発生させます。
view、action、resource、errorのデータがGuanceに送信されていることを確認します。- 同一ユーザーが複数ウィンドウ、またはローカルページとリモートページを切り替えた際のセッションが期待どおりであることを確認します。
ローカルでデバッグする場合は、一時的に beforeSend でイベントタイプを出力することもできます:
datafluxRum.init({
// ...
beforeSend: (event) => {
console.log('[RUM]', event.type, event)
return true
}
})
よくある質問¶
main process にデータがないのはなぜですか?¶
RUM SDK はブラウザ側の SDK であり、renderer process 内のページ操作のみを収集します。main process のクラッシュ、IPC、ファイルシステム、ネイティブモジュールのエラーは、アプリケーション独自のログまたはクラッシュ収集の仕組みで処理する必要があります。
file:// ページにセッションがないのはなぜですか?¶
通常は、sessionPersistence: 'local-storage' が設定されていないか、renderer ページが動作する環境で localStorage が無効になっていることが原因です。まずこの設定と localStorage の利用可否を確認してください。
ローカルページからリモートページへ遷移するとセッションが変わるのはなぜですか?¶
file:// と https:// は異なるオリジンであるため、ブラウザは同じ cookie や localStorage を共有しません。setUser() で安定したユーザー ID を設定し、分析時にユーザー単位で関連付けることをお勧めします。
複数ウィンドウで非常に短いセッションが発生するのはなぜですか?¶
複数ウィンドウを同時に初期化すると、localStorage のウィンドウ間同期にごく短い遅延が生じることがあります。同じ瞬間に多数のウィンドウを作成・初期化しないようにし、ウィンドウ作成の間に短い間隔を空けることをお勧めします。