Интеграция 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 пуст. Если пользователь не дал согласие, он записывает лог и возвращается без запуска. В противном случае он подключается к Mellowtel, чтобы начать обработку запросов. Вызов не блокирует UI рендерера, поэтому окна остаются отзывчивыми, пока устанавливается соединение.

​

Необязательно: уменьшение неожиданных запросов ОС

​

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

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

​

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

​

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

​

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

• init(): Promise<void> запускает сервис, если пользователь дал согласие, или возвращается без запуска, если нет. Выдает ошибку только если ключ конфигурации пуст.
• shutdown(): Promise<void> очищает ресурсы SDK при закрытии приложения. Закрывает соединение с Mellowtel, освобождает изолированные окна запросов и очищает фоновые таймеры. Сохраняет предпочтение пользователя относительно согласия.
• requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined> показывает встроенный нативный диалог согласия и сохраняет результат. Возвращает true при принятии, false при отклонении или закрытии, undefined, если согласие уже было дано.
• showConsentSettings(window: BrowserWindow): Promise<void> показывает встроенный диалог управления согласием. SDK обрабатывает переходы включения / отключения внутренне, когда пользователь переключает свой выбор.

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

​

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

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

​

Приложения с одним окном

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

​

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