Руководство по интеграции и согласию с Mellowtel Electron SDK

Интегрируйте Mellowtel в ваше кросс-платформенное приложение Electron, чтобы пользователи могли делиться неиспользованной интернет-пропускной способностью в обмен на вознаграждения или премиальные функции. Electron SDK работает везде, где работает 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. Установка пакета

Из корня вашего проекта установите Electron SDK:

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(), и вы должны предоставить способ управления их состоянием согласия в любое время.

У вас есть два пути для обработки согласия:

Используйте встроенный нативный диалог через requestConsent(window, incentive). Это самый быстрый путь и то, что показано в приведенном выше фрагменте. Он отображает нативный dialog.showMessageBox Electron с вашим текстом стимула в качестве заголовка и автоматически сохраняет решение пользователя.
Создайте свой собственный интерфейс согласия и управляйте SDK через optIn(), optOut() и getOptInStatus(). Используйте это, если вы хотите собственный брендинг, более богатые объяснения или локализацию, выходящую за рамки того, что предлагает нативный диалог.

Что должно включать ваше диалоговое окно согласия

Объясните, что делает Mellowtel

Используйте простой язык. Пример: “Это приложение использует Mellowtel для обмена вашей неиспользованной интернет-пропускной способностью. Взамен вы получаете [преимущество/функцию]. Вы можете отказаться в любое время в настройках.”

Дайте пользователям четкий выбор

Включите отдельные опции Принять и Отклонить.

Ссылка на политики

Включите ссылки на Условия использования и Политику конфиденциальности.

Позвольте пользователям изменить свое согласие позже

Mellowtel предоставляет встроенный диалог настроек через showConsentSettings(window). Он отображает нативный диалог с кнопками Включить / Отключить, которые соответствуют текущему состоянию пользователя, и внутренне вызывает 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 } } возвращает все три счетчика за один вызов.

Завершение работы и жизненный цикл

Electron SDK не регистрирует свои собственные обработчики 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

Состояние переживает обновления приложения. Удаление вашего приложения не очистит его автоматически, если только ваш деинсталлятор явно не удаляет каталог конфигурации приложения.

Устранение неполадок

Ошибка "Пакет не найден" во время установки

Убедитесь, что .npmrc находится в корне проекта, рядом с вашим package.json.
Убедитесь, что в токене нет начальных или конечных пробелов.
Очистите кэш npm и повторите попытку, запустив npm cache clean --force, а затем npm install.

Ошибка "Unauthorized" или 401 во время установки

Убедитесь, что токен в .npmrc правильный и активный. Если вы не уверены, запросите новый токен по info@mellowtel.com.
Подтвердите, что строка @mellowtel-inc:registry присутствует и указывает на https://npm.pkg.github.com/.

Диалог согласия никогда не появляется

Убедитесь, что вы вызываете requestConsent после того, как app.whenReady() разрешен, и с действительной, не уничтоженной ссылкой BrowserWindow.
Если вы используете setupMellowtelApp(), убедитесь, что он вызывается до app.whenReady(), а не после.

"init() выполняется без ошибок, но ничего не происходит"

Это так задумано. init() тихо завершает работу, если пользователь не дал согласие. Проверьте getOptInStatus(), чтобы подтвердить. Если он возвращает undefined или false, сначала выполните requestConsent. Обратите внимание, что внутренний журнал “Пользователь не дал согласие” подавляется, когда disableLogs оставлен по умолчанию (см. “Журналы молчат” ниже), поэтому терминал не дает вам сигнала в любом случае, пока вы не измените этот флаг.

Журналы молчат

Опция конструктора disableLogs по умолчанию равна true. Передайте { disableLogs: false } в качестве второго аргумента конструктору во время интеграции, чтобы отобразить состояние соединения и активность запросов в вашем терминале. Это также самый быстрый способ отличить “не дал согласие” тихий бездействие (см. выше) от реальной ошибки соединения.

Оценочное время завершения: 10-15 минут. Если вам нужна помощь или у вас есть отзывы, свяжитесь с нами по info@mellowtel.com или присоединяйтесь к нашему сообществу в Discord.

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

​Установка

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

​2. Установка пакета

​3. Добавьте в ваш код

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

​Согласие пользователя

​Что должно включать ваше диалоговое окно согласия

​Позвольте пользователям изменить свое согласие позже

​Справочник методов

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

​Сохранение согласия

​Устранение неполадок

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

Установка

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

2. Установка пакета

3. Добавьте в ваш код

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

Согласие пользователя

Что должно включать ваше диалоговое окно согласия

Позвольте пользователям изменить свое согласие позже

Справочник методов

Завершение работы и жизненный цикл

Сохранение согласия

Устранение неполадок