在你的 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) 渲染一个原生 Electron 消息框，锚定到你传入的 BrowserWindow。第二个参数是对话框的显著标题（例如，“获取 3 个月免费”），显示在 Mellowtel 的固定说明上方。如果用户接受，它解析为 true，如果用户拒绝或关闭对话框，则为 false，如果同意已在文件中，则为 undefined。SDK 会自动保存选择加入的决定，因此你不需要在之后调用 optIn()。
• init() 仅在 configurationKey 为空时抛出错误。如果用户尚未选择加入，它会记录并返回而不启动。否则，它会连接到 Mellowtel，以便开始处理请求。该调用对渲染器 UI 是非阻塞的，因此在建立连接时窗口保持响应。

​

可选：减少意外的操作系统提示

​

用户同意

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 } } 一次调用返回所有三个计数器。

​

生命周期和应用关闭

• 关闭与 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

​

故障排除