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

​

Додатково: зменшення несподіваних запитів ОС

​

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

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

​

Що має містити ваш діалог згоди

​

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

​

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

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

• 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

​

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