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

​

生命周期和应用关闭

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

​

故障排除