Інтеграція Mellowtel у ваш додаток Electron

​

Попередні вимоги

• Обліковий запис 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 порожній. Якщо користувач не погодився, він записує лог і повертається безшумно. В іншому випадку він відкриває WebSocket до бекенду Mellowtel. Виклик не блокує UI рендерера, тому вікна залишаються чутливими під час встановлення з’єднання.

​

Запобігання перериванням системних діалогів (рекомендується)

​

Згода користувача

1. Використовуйте вбудований нативний діалог через requestConsent(window, incentive). Це найшвидший шлях і саме те, що показує наведений вище фрагмент. Він відображає нативний діалог Electron dialog.showMessageBox з вашим текстом стимулу як заголовком і автоматично зберігає рішення користувача.
2. Створіть власний інтерфейс згоди і керуйте SDK через optIn(), optOut(), і getOptInStatus(). Використовуйте це, якщо ви хочете власний брендинг, багатші пояснення або локалізацію, що виходить за межі того, що пропонує нативний діалог.

​

Що має включати ваш діалог згоди

​

Дозвольте користувачам змінювати свою згоду пізніше

​

Довідка по методам

• 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 обробляє переходи opt-in / opt-out внутрішньо, коли користувач перемикає свій вибір.

• optIn(): Promise<void> позначає користувача як такого, що погодився, без показу діалогу. Використовуйте це лише після збору згоди через ваш власний інтерфейс.
• 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

​

Усунення несправностей