ElectronアプリにMellowtelを統合する

​

前提条件

• Mellowtelアカウントと構成キー（ダッシュボードから取得）。
• メインプロセスにアクセスできるElectronアプリケーション。

​

インストール

​

1. パッケージをインストールする

npm install mellowtel-electron

​

2. コードに追加する

import { app, BrowserWindow } from 'electron';
import Mellowtel, { setupMellowtelApp } from 'mellowtel-electron';

// オプション: システムダイアログを防ぐためにapp.readyの前に呼び出す
setupMellowtelApp();

// アプリが準備完了したら、ウィンドウを作成する
app.whenReady().then(async () => {
  let win = createWindow();

  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

  await mellowtel.requestConsent(win, "3ヶ月無料")
  await mellowtel.init()
});

• new Mellowtel(configurationKey, options?)はSDKをインスタンス化します。現在利用可能な唯一のオプションはdisableLogsで、デフォルトはtrueです。統合中はfalseに設定して、ターミナルで接続状態とリクエスト活動を確認できるようにします。
• requestConsent(window, incentive)は、渡されたBrowserWindowにアンカーされたネイティブのElectronメッセージボックスをレンダリングします。第2引数はダイアログの目立つ見出し（例：“3ヶ月無料”）で、Mellowtelが何をするかの固定説明の上に表示されます。ユーザーが受け入れた場合はtrue、拒否またはダイアログを閉じた場合はfalse、すでに同意が記録されている場合はundefinedを解決します。SDKはオプトインの決定を自動的に保持するため、後でoptIn()を呼び出す必要はありません。
• init()は、configurationKeyが空の場合にのみスローします。ユーザーがオプトインしていない場合は、ログを記録して静かにリターンします。それ以外の場合は、MellowtelのバックエンドにWebSocketを開きます。この呼び出しはレンダラーUIに対してブロックしないため、接続が確立される間もウィンドウは応答性を保ちます。

​

システムダイアログの中断を防ぐ（推奨）

​

ユーザーの同意

1. 組み込みのネイティブダイアログを使用する requestConsent(window, incentive)を介して。これは最も迅速な方法であり、上記のスニペットが示しているものです。インセンティブのコピーを見出しとして持つネイティブのElectron dialog.showMessageBoxをレンダリングし、ユーザーの決定を自動的に保持します。
2. 独自の同意UIを構築する optIn(), optOut(), getOptInStatus()を通じてSDKを駆動します。ネイティブダイアログが提供するものを超えたカスタムブランディング、より豊かな説明、またはローカリゼーションが必要な場合に使用します。

​

同意ダイアログに含めるべきもの

​

後でユーザーが同意を変更できるようにする

​

メソッドリファレンス

• init(): Promise<void>は、ユーザーがオプトインしている場合にサービスを開始し、そうでない場合は静かに早期リターンします。構成キーが空の場合にのみスローします。
• shutdown(): Promise<void>は、アプリケーションが閉じるときにSDKリソースをクリーンアップします。WebSocketを閉じ、隠れたワーカウィンドウを破棄し、バックグラウンドタイマーをクリアします。ユーザーのオプトインの好みを保持します。
• requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined>は、組み込みのネイティブ同意ダイアログを表示し、結果を保持します。受け入れの場合はtrue、拒否または閉じた場合はfalse、すでに同意が与えられている場合はundefinedを返します。
• showConsentSettings(window: BrowserWindow): Promise<void>は、組み込みの同意管理ダイアログを表示します。ユーザーが選択を切り替えたときにSDKが内部でオプトイン/オプトアウトの遷移を処理します。

• optIn(): Promise<void>は、ダイアログを表示せずにユーザーをオプトインとしてフラグします。独自のUIを通じて同意を収集した後にのみ使用します。
• optOut(): Promise<void>は、ユーザーをオプトアウトとしてフラグし、完全なクリーンアップを実行します（shutdown()と同じリソース、さらに保存された同意の好みをクリアします）。その後にshutdown()を呼び出す必要はありません。
• getOptInStatus(): boolean | undefinedは、現在のオプトイン状態を返します。ユーザーが選択をしたことがない場合はundefinedを返します。
• getNodeId(): stringは、このインストールのMellowtelノード識別子を返します。サポートチケットを提出する際に便利です。

• getTotalRequestCount(): numberは、インストール以来処理された総リクエスト数を返します。
• getDailyRequestCount(): numberは、今日処理されたリクエスト数を返します。
• getRequestCountForDate(date: string): numberは、特定の日付YYYY-MM-DDのカウントを返します。
• getDailyRequestsHistory(): { [date: string]: number }は、すべての日ごとのカウントをマップとして返します。
• getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number }は、日付範囲のカウントを返します。
• getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } }は、3つのカウンターすべてを1回の呼び出しで返します。

​

ライフサイクルとアプリのシャットダウン

• WebSocket接続を閉じます。
• 隠れたワーカウィンドウを破棄します。
• バックグラウンドタイマーとネットワークリソースをクリアします。
• ユーザーのオプトインの好みを保持します。

​

シングルウィンドウアプリケーション

mainWindow.on('closed', async () => {
  mainWindow = null;

  if (process.platform !== 'darwin') {
    await mellowtel.shutdown();
    app.quit();
  }
});

​

トレイアプリケーション

trayQuitItem.click = async () => {
  await mellowtel.shutdown();
  app.quit();
};

​

macOSアプリケーション

​

オプトアウト

await mellowtel.optOut();

​

再起動

await mellowtel.optIn(); // optOut()の後にのみ必要
await mellowtel.init();

​

同意の持続性

• macOS: ~/Library/Application Support/<YourAppName>/config.json
• Windows: %APPDATA%\<YourAppName>\config.json
• Linux: ~/.config/<YourAppName>/config.json

​

トラブルシューティング