Skip to main content
Інтегруйте Mellowtel у ваш кросплатформенний додаток Electron, щоб дозволити користувачам ділитися своїм невикористаним інтернет-трафіком в обмін на винагороди або преміум-функції. SDK для Electron працює всюди, де працює Electron (macOS, Windows і Linux).
Згода користувача є обов’язковою. SDK працює лише тоді, коли користувач явно погодився. init() тихо повертається раніше, якщо немає згоди, тому якщо ви бачите, що SDK запускається без помилок, але ніколи не надсилає трафік, найімовірніша причина полягає в тому, що користувач ще не погодився.

​
Передумови

  • Обліковий запис Mellowtel і ключ конфігурації (отримайте свій на dashboard).
  • Додаток Electron з доступом до основного процесу.

​
Встановлення

​
1. Налаштування автентифікації npm

Створіть файл .npmrc у кореневій директорії вашого проекту, щоб вказати npm на реєстр Mellowtel GitHub Packages і автентифікувати встановлення: 
@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN
Замініть YOUR_NPM_TOKEN на токен встановлення нижче. Натисніть, щоб відкрити, а потім скористайтеся значком копіювання на блоці коду, щоб скопіювати його в буфер обміну. 
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

​
2. Встановіть пакет

З кореня вашого проекту встановіть SDK для Electron: 
npm install @mellowtel-inc/mellowtel-electron

​
3. Додайте до вашого коду

У вашому файлі основного процесу Electron (зазвичай main.ts або main.js), імпортуйте SDK, створіть його екземпляр з вашим ключем конфігурації, запросіть згоду користувача, а потім викличте init(), щоб запустити сервіс. 
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()
});
Замініть YOUR_CONFIGURATION_KEY на ключ з вашого Mellowtel dashboard.
Що робить кожен виклик:
  • 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 рендерера, тому вікна залишаються чуйними, поки з’єднання встановлюється.

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

SDK постачається з додатковим помічником, setupMellowtelApp(), який налаштовує командні прапори Electron для придушення системних діалогів (спливаючі вікна автозаповнення, панелі перекладу, запити автентифікації NTLM / Kerberos, інтеграція з менеджером паролів, накладки медіа, діалоги першого запуску), які інакше переривали б ваших користувачів, коли приховані вікна Mellowtel обробляють запити у фоновому режимі. Викличте його на початку вашого файлу основного процесу, перед app.whenReady(), і імпортуйте його разом із експортом за замовчуванням з @mellowtel-inc/mellowtel-electron. Дивіться upstream README для канонічного використання.

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

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

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

1

Поясніть, що робить Mellowtel

Використовуйте просту мову. Приклад: “Цей додаток використовує Mellowtel для обміну вашим невикористаним інтернет-трафіком. Взамін ви отримуєте [вигода/функція]. Ви можете відмовитися в будь-який час у налаштуваннях.”
2

Дайте користувачам чіткий вибір

Включіть чіткі опції Прийняти та Відхилити.
3

Посилання на політики

Включіть посилання на Умови використання та Політику конфіденційності.

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

Mellowtel надає вбудований діалог налаштувань через showConsentSettings(window). Він відображає рідний діалог з кнопками Opt In / Opt Out, які відповідають поточному стану користувача, і внутрішньо викликає optIn() або optOut() (плюс повторне підключення WebSocket при згоді), коли користувач перемикає. Підключіть його до пункту меню або кнопки налаштувань у вашому додатку, щоб користувачі могли переглянути свій вибір. Якщо ви віддаєте перевагу створенню власного екрану налаштувань, викличте getOptInStatus(), щоб прочитати поточний стан, і optIn() / optOut(), щоб змінити його.

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

Клас Mellowtel надає наступні публічні методи. Усі вони доступні на екземплярі, який ви створили за допомогою new Mellowtel(configurationKey, options?). Життєвий цикл
  • 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 для цієї установки. Корисно при поданні запитів на підтримку.
Лічильники запитів Кількість запитів зберігається локально через electron-store і зберігається після перезапуску додатка. Відображайте їх у вашому власному інтерфейсі, якщо ви хочете показати користувачам вплив їхньої згоди.
  • 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 } } повертає всі три лічильники в одному виклику.

​
Завершення роботи та життєвий цикл

SDK для Electron не реєструє власні обробники before-quit або will-quit. Коли ваш процес Electron завершує роботу, фонове з’єднання WebSocket розривається разом з ним, і ніякого явного очищення з вашого боку не потрібно. Якщо ви хочете відключити Mellowtel під час сеансу (наприклад, коли користувач перемикає налаштування “пауза” у вашому додатку), викличте optOut(). Це очищає прапор згоди і закриває активне з’єднання. Щоб підключитися знову, викличте optIn(), а потім init().

​
Збереження згоди

Стан згоди зберігається в стандартному для платформи шляху конфігурації electron-store:
  • macOS: ~/Library/Application Support/<YourAppName>/config.json
  • Windows: %APPDATA%\<YourAppName>\config.json
  • Linux: ~/.config/<YourAppName>/config.json
Стан зберігається після оновлень додатка. Видалення вашого додатка не очистить його автоматично, якщо ваш деінсталятор явно не видаляє директорію конфігурації додатка.

​
Вирішення проблем

  1. Переконайтеся, що .npmrc знаходиться в корені проекту, поруч з вашим package.json.
  2. Переконайтеся, що токен не має пробілів на початку або в кінці.
  3. Очистіть кеш npm і повторіть спробу, виконавши npm cache clean --force, а потім npm install.
  1. Переконайтеся, що токен у .npmrc правильний і активний. Якщо ви не впевнені, запросіть новий токен з info@mellowtel.com.
  2. Підтвердіть, що рядок @mellowtel-inc:registry присутній і вказує на https://npm.pkg.github.com/.
  1. Переконайтеся, що ви викликаєте requestConsent після того, як app.whenReady() було вирішено, і з дійсним, не знищеним посиланням BrowserWindow.
  2. Якщо ви використовуєте setupMellowtelApp(), переконайтеся, що він викликаний перед app.whenReady(), а не після.
Це за задумом. init() тихо повертається раніше, якщо користувач не погодився. Перевірте getOptInStatus(), щоб підтвердити. Якщо він повертає undefined або false, спочатку запустіть requestConsent. Зверніть увагу, що внутрішній лог “Користувач не погодився” приглушений, коли disableLogs залишається за замовчуванням (див. “Логи мовчать” нижче), тому термінал не дає вам жодного сигналу в будь-якому випадку, поки ви не зміните цей прапор.
Опція конструктора disableLogs за замовчуванням встановлена в true. Передайте { disableLogs: false } як другий аргумент до конструктора під час інтеграції, щоб відобразити стан з’єднання та активність запитів у вашому терміналі. Це також найшвидший спосіб відрізнити “не погоджено” тихе бездіяльність (див. вище) від реальної помилки з’єднання.
Орієнтовний час завершення: 10-15 хвилин. Якщо вам потрібна допомога або у вас є відгуки, зв’яжіться з нами за адресою info@mellowtel.com або приєднуйтеся до нашої спільноти Discord.