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

​

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

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

​

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

​

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

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

​

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

​

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

​

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

• init(): Promise<void> запускає сервіс, якщо користувач погодився, або тихо повертається раніше, якщо ні. Кидає виключення лише тоді, коли ключ конфігурації порожній.
• 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> позначає користувача як такого, що відмовився, і закриває активне з’єднання 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

​

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