> ## 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 Packages і аутентифікувати встановлення:
```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. Виклик не блокує інтерфейс користувача, тому вікна залишаються чутливими, поки з'єднання встановлюється.
### Запобігання перериванням системних діалогів (рекомендується)
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)`. Це найшвидший шлях і саме те, що показує наведений вище фрагмент. Він відображає нативний Electron `dialog.showMessageBox` з вашим текстом стимулу як заголовок і автоматично зберігає рішення користувача.
2. **Створіть свій власний інтерфейс згоди** і керуйте SDK через `optIn()`, `optOut()`, і `getOptInStatus()`. Використовуйте це, якщо ви хочете налаштувати брендинг, багатші пояснення або локалізацію, що виходить за межі того, що пропонує нативний діалог.
### Що має включати ваш діалог згоди
Використовуйте просту мову. Приклад: *"Цей додаток використовує Mellowtel для обміну вашим невикористаним інтернет-трафіком. В обмін ви отримуєте \[вигода/функція]. Ви можете відмовитися в будь-який час у налаштуваннях."*
Включіть окремі опції Прийняти та Відхилити.
Включіть посилання на [Умови використання](https://www.mellowtel.com/terms-and-conditions) та [Політику конфіденційності](https://www.mellowtel.com/privacy-policy).
### Дозвольте користувачам змінювати свою згоду пізніше
Mellowtel надає вбудований діалог налаштувань через `showConsentSettings(window)`. Він відображає нативний діалог з кнопками Opt In / Opt Out, які відповідають поточному стану користувача, і внутрішньо викликає `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 обробляє переходи opt-in / opt-out внутрішньо, коли користувач перемикає свій вибір.
**Ручне керування згодою**
* `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).