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 и аутентифицировать установку: 
@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. См. основное руководство для канонического использования.

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

Отображение диалога согласия обязательно. Вы должны позволить пользователям явно согласиться перед вызовом 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.