Интеграция Mellowtel в ваше приложение на Electron

​

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

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

​

Установка

​

1. Установите пакет

npm install mellowtel-electron

​

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

import { app, BrowserWindow } from 'electron';
import Mellowtel, { setupMellowtelApp } from 'mellowtel-electron';

// Необязательно: вызовите ДО app.ready, чтобы предотвратить системные диалоги
setupMellowtelApp();

// Когда приложение готово, создайте окно
app.whenReady().then(async () => {
  let win = createWindow();

  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

  await mellowtel.requestConsent(win, "Получите 3 месяца бесплатно")
  await mellowtel.init()
});

• 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 рендерера, поэтому окна остаются отзывчивыми, пока устанавливается соединение.

​

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

​

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

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

​

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

​

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

​

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

• init(): Promise<void> запускает сервис, если пользователь дал согласие, или тихо завершает работу, если нет. Выдает ошибку только тогда, когда ключ конфигурации пуст.
• shutdown(): Promise<void> очищает ресурсы SDK при закрытии приложения. Закрывает WebSocket, уничтожает скрытые окна рабочих процессов и очищает фоновые таймеры. Сохраняет предпочтение пользователя о согласии.
• 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> помечает пользователя как отказавшегося и выполняет полную очистку (те же ресурсы, что и shutdown(), плюс очистка сохраненного предпочтения согласия). Нет необходимости вызывать shutdown() после этого.
• getOptInStatus(): boolean | undefined возвращает текущее состояние согласия, или undefined, если пользователь никогда не делал выбор.
• getNodeId(): string возвращает идентификатор узла Mellowtel для этой установки. Полезно при подаче заявок в службу поддержки.

• 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 } } возвращает все три счетчика в одном вызове.

​

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

• Закрывает соединение WebSocket.
• Уничтожает скрытые окна рабочих процессов.
• Очищает фоновые таймеры и сетевые ресурсы.
• Сохраняет предпочтение пользователя о согласии.

​

Однооконные приложения

mainWindow.on('closed', async () => {
  mainWindow = null;

  if (process.platform !== 'darwin') {
    await mellowtel.shutdown();
    app.quit();
  }
});

​

Приложения в трее

trayQuitItem.click = async () => {
  await mellowtel.shutdown();
  app.quit();
};

​

Приложения для macOS

​

Отказ от участия

await mellowtel.optOut();

​

Повторный запуск

await mellowtel.optIn(); // Нужно только после optOut()
await mellowtel.init();

​

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

• macOS: ~/Library/Application Support/<YourAppName>/config.json
• Windows: %APPDATA%\<YourAppName>\config.json
• Linux: ~/.config/<YourAppName>/config.json

​

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