> ## Documentation Index > Fetch the complete documentation index at: https://www.mellowtel.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Интеграция Mellowtel в ваше приложение Electron Интегрируйте Mellowtel в ваше кросс-платформенное приложение Electron, чтобы пользователи могли делиться неиспользованной интернет-пропускной способностью в обмен на вознаграждения или премиальные функции. Electron SDK работает везде, где работает Electron (macOS, Windows и Linux). **Согласие пользователя обязательно.** SDK работает только при явном согласии пользователя. `init()` тихо завершает работу, если согласие не получено, поэтому если вы видите, что SDK запускается без ошибок, но не отправляет трафик, скорее всего, пользователь еще не дал согласие. ## Предварительные требования * Учетная запись Mellowtel и ключ конфигурации (получите его на [панели управления](https://www.mellowtel.com/mellowtel-auth/)). * Приложение Electron с доступом к основному процессу. *** ## Установка ### 1. Настройка аутентификации npm Создайте файл `.npmrc` в корневом каталоге вашего проекта, чтобы указать npm на регистр пакетов Mellowtel GitHub и аутентифицировать установку: ```bash theme={null} @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: ```bash theme={null} npm install @mellowtel-inc/mellowtel-electron ``` ### 3. Добавьте в ваш код В вашем основном файле процесса Electron (обычно `main.ts` или `main.js`) импортируйте SDK, создайте его экземпляр с вашим ключом конфигурации, запросите согласие пользователя, а затем вызовите `init()`, чтобы запустить сервис. ```typescript theme={null} 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](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional) для канонического использования. *** ## Согласие пользователя Отображение диалога согласия **обязательно**. Вы должны позволить пользователям явно согласиться перед вызовом `init()`, и вы должны предоставить способ управления их состоянием согласия в любое время. У вас есть два пути для обработки согласия: 1. **Используйте встроенный нативный диалог** через `requestConsent(window, incentive)`. Это самый быстрый путь и то, что показано в приведенном выше фрагменте. Он отображает нативный `dialog.showMessageBox` Electron с вашим текстом стимула в качестве заголовка и автоматически сохраняет решение пользователя. 2. **Создайте свой собственный интерфейс согласия** и управляйте SDK через `optIn()`, `optOut()` и `getOptInStatus()`. Используйте это, если вы хотите собственный брендинг, более богатые объяснения или локализацию, выходящую за рамки того, что предлагает нативный диалог. ### Что должно включать ваше диалоговое окно согласия Используйте простой язык. Пример: *"Это приложение использует Mellowtel для обмена вашей неиспользованной интернет-пропускной способностью. Взамен вы получаете \[преимущество/функцию]. Вы можете отказаться в любое время в настройках."* Включите отдельные опции Принять и Отклонить. Включите ссылки на [Условия использования](https://www.mellowtel.com/terms-and-conditions) и [Политику конфиденциальности](https://www.mellowtel.com/privacy-policy). ### Позвольте пользователям изменить свое согласие позже Mellowtel предоставляет встроенный диалог настроек через `showConsentSettings(window)`. Он отображает нативный диалог с кнопками Включить / Отключить, которые соответствуют текущему состоянию пользователя, и внутренне вызывает `optIn()` или `optOut()` (плюс переподключение WebSocket при включении), когда пользователь переключает. Подключите его к пункту меню или кнопке настроек в вашем приложении, чтобы пользователи могли пересмотреть свой выбор. Если вы предпочитаете создать свой собственный экран настроек, вызовите `getOptInStatus()`, чтобы прочитать текущее состояние, и `optIn()` / `optOut()`, чтобы изменить его. *** ## Справочник методов Класс `Mellowtel` предоставляет следующие публичные методы. Все они доступны на экземпляре, который вы создали с помощью `new Mellowtel(configurationKey, options?)`. **Жизненный цикл** * `init(): Promise` запускает сервис, если пользователь дал согласие, или тихо завершает работу, если нет. Выдает ошибку только если ключ конфигурации пуст. * `requestConsent(window: BrowserWindow, incentive: string): Promise` отображает встроенный нативный диалог согласия и сохраняет результат. Возвращает `true` при принятии, `false` при отклонении или закрытии, `undefined`, если согласие уже было дано. * `showConsentSettings(window: BrowserWindow): Promise` отображает встроенный диалог управления согласием. SDK обрабатывает переходы включения / отключения внутренне, когда пользователь переключает свой выбор. **Ручное управление согласием** * `optIn(): Promise` отмечает пользователя как давшего согласие без отображения диалога. Используйте это только после получения согласия через ваш собственный интерфейс. * `optOut(): Promise` отмечает пользователя как отказавшегося и закрывает активное соединение 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//config.json` * Windows: `%APPDATA%\\config.json` * Linux: `~/.config//config.json` Состояние переживает обновления приложения. Удаление вашего приложения не очистит его автоматически, если только ваш деинсталлятор явно не удаляет каталог конфигурации приложения. *** ## Устранение неполадок 1. Убедитесь, что `.npmrc` находится в корне проекта, рядом с вашим `package.json`. 2. Убедитесь, что в токене нет начальных или конечных пробелов. 3. Очистите кэш npm и повторите попытку, запустив `npm cache clean --force`, а затем `npm install`. 1. Убедитесь, что токен в `.npmrc` правильный и активный. Если вы не уверены, запросите новый токен по [info@mellowtel.com](mailto: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](mailto:info@mellowtel.com) или присоединяйтесь к нашему [сообществу в Discord](https://discord.com/invite/txAZp4MSDe).