ElectronアプリにMellowtelを統合する

​

前提条件

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

​

インストール

​

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

npm install mellowtel-electron

​

2. コードに追加

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

// オプション：予期しないOSプロンプトを減らすために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に接続し、リクエストの処理を開始します。この呼び出しはレンダラーUIに対して非ブロッキングであるため、接続が確立される間もウィンドウは応答性を保ちます。

​

オプション：予期しないOSプロンプトを減らす

​

ユーザーの同意

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

​

同意ダイアログに含めるべき内容

​

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

​

メソッドリファレンス

• init(): Promise<void>は、ユーザーがオプトインしている場合にサービスを開始し、そうでない場合は開始せずに戻ります。設定キーが空の場合のみスローします。
• shutdown(): Promise<void>は、アプリケーションが閉じるときにSDKリソースをクリーンアップします。Mellowtelへの接続を閉じ、分離されたリクエストウィンドウを解放し、バックグラウンドタイマーをクリアします。ユーザーのオプトインの好みを保持します。
• 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回の呼び出しで返します。

​

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

• Mellowtelへの接続を閉じます。
• 分離されたリクエストウィンドウを解放します。
• バックグラウンドタイマーをクリアします。
• ユーザーのオプトインの好みを保持します。

​

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

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

​

トラブルシューティング