在你的 Electron 应用中集成 Mellowtel

​

前提条件

• 一个 Mellowtel 账户和配置密钥（从 dashboard 获取）。
• 一个可以访问主进程的 Electron 应用。

​

安装

​

1. 配置 npm 认证

@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN

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

​

2. 安装包

npm install @mellowtel-inc/mellowtel-electron

​

3. 添加到你的代码中

import { app, BrowserWindow } from 'electron';
import Mellowtel from '@mellowtel-inc/mellowtel-electron';


// 当应用准备好时，创建窗口
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> 如果用户已选择加入，则启动服务，否则静默提前返回。仅在配置密钥为空时抛出异常。
• requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined> 显示内置的原生同意对话框并持久化结果。接受时返回 true，拒绝或关闭时返回 false，如果已给予同意则返回 undefined。
• showConsentSettings(window: BrowserWindow): Promise<void> 显示内置的管理同意对话框。当用户切换选择时，SDK 内部处理选择加入/选择退出的过渡。

• optIn(): Promise<void> 将用户标记为已选择加入而不显示对话框。仅在通过你自己的 UI 收集同意后使用此方法。
• optOut(): Promise<void> 将用户标记为选择退出并关闭活动的 WebSocket 连接。
• 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 } } 一次调用返回所有三个计数器。

​

关闭和生命周期

​

同意持久化

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

​

故障排除