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

​
Предварительные требования

  • Учетная запись Mellowtel и ключ конфигурации (получите его на панели управления).
  • Приложение на Electron с доступом к основному процессу.

​
Установка

​
1. Настройка аутентификации npm

Создайте файл .npmrc в корневом каталоге вашего проекта, чтобы указать npm на реестр пакетов Mellowtel GitHub и аутентифицировать установку: 
@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. Вызов не блокирует UI рендерера, поэтому окна остаются отзывчивыми, пока устанавливается соединение.

​
Предотвращение системных диалогов (рекомендуется)

SDK поставляется с дополнительным помощником, setupMellowtelApp(), который настраивает флаги командной строки Electron, чтобы подавлять системные диалоги (всплывающие окна автозаполнения, панели перевода, запросы NTLM / Kerberos аутентификации, интеграцию с менеджером паролей, медиа-оверлеи, диалоги первого запуска), которые в противном случае прерывали бы ваших пользователей, когда скрытые окна 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 обрабатывает переходы между состояниями согласия внутренне, когда пользователь переключает свой выбор.
Ручное управление согласием
  • 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.