Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mellowtel.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

  • Обліковий запис Mellowtel і ключ конфігурації (отримайте його на панелі керування).
  • Додаток 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.
Що робить кожен виклик:
  • new Mellowtel(configurationKey, options?) створює екземпляр SDK. Єдиний доступний параметр на сьогодні — це disableLogs, який за замовчуванням встановлено в true. Встановіть його в false під час інтеграції, щоб ви могли бачити стан з’єднання та активність запитів у вашому терміналі.
  • requestConsent(window, incentive) відображає нативне повідомлення Electron, прив’язане до BrowserWindow, яке ви передаєте. Другий аргумент — це помітний заголовок діалогу (наприклад, "Отримайте 3 місяці безкоштовно"), показаний вище фіксованого пояснення того, що робить Mellowtel. Він повертає true, якщо користувач приймає, false, якщо користувач відхиляє або закриває діалог, і undefined, якщо згода вже є в файлі. SDK автоматично зберігає рішення про згоду, тому вам не потрібно викликати optIn() після цього.
  • init() викликає помилку лише тоді, коли configurationKey порожній. Якщо користувач не дав згоди, він записує в журнал і повертається тихо. В іншому випадку він відкриває WebSocket до бекенду Mellowtel. Виклик не блокує інтерфейс користувача рендера, тому вікна залишаються чутливими під час встановлення з’єднання.

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

SDK постачається з додатковим помічником, setupMellowtelApp(), який налаштовує командні прапори Electron, щоб придушити системні діалоги (випливаючі вікна автозаповнення, панелі перекладу, запити NTLM / Kerberos auth, інтеграцію з менеджером паролів, медіа-оверлеї, діалоги першого запуску), які інакше переривали б ваших користувачів, коли приховані вікна Mellowtel обробляють запити у фоновому режимі. Викличте його на початку вашого файлу основного процесу, перед app.whenReady(), і імпортуйте його разом із експортом за замовчуванням з @mellowtel-inc/mellowtel-electron. Дивіться вихідний 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 } як другий аргумент до конструктора під час інтеграції, щоб відобразити стан з’єднання та активність запитів у вашому терміналі. Це також найшвидший спосіб відрізнити “не дав згоди” тихий no-op (див. вище) від реальної помилки з’єднання.
Орієнтовний час завершення: 10-15 хвилин. Якщо вам потрібна допомога або у вас є відгуки, зв’яжіться з нами за адресою info@mellowtel.com або приєднуйтесь до нашої спільноти Discord.