Integre o Mellowtel no seu App Electron

​

Pré-requisitos

• Uma conta Mellowtel e chave de configuração (obtenha a sua no painel de controle).
• Um aplicativo Electron com acesso ao processo principal.

​

Instalação

​

1. Instale o Pacote

npm install mellowtel-electron

​

2. Adicione ao Seu Código

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

// Opcional: Chame ANTES de app.ready para evitar diálogos do sistema
setupMellowtelApp();

// Quando o app estiver pronto, crie a janela
app.whenReady().then(async () => {
  let win = createWindow();

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

  await mellowtel.requestConsent(win, "Ganhe 3 meses grátis")
  await mellowtel.init()
});

• new Mellowtel(configurationKey, options?) instancia o SDK. A única opção disponível hoje é disableLogs, que por padrão é true. Defina como false durante a integração para ver o estado da conexão e a atividade de requisição no seu terminal.
• requestConsent(window, incentive) renderiza uma caixa de mensagem nativa do Electron ancorada ao BrowserWindow que você passa. O segundo argumento é o título proeminente do diálogo (por exemplo, "Ganhe 3 meses grátis"), mostrado acima de uma explicação fixa do que o Mellowtel faz. Resolve para true se o usuário aceitar, false se o usuário recusar ou fechar o diálogo, e undefined se o consentimento já estiver registrado. O SDK persiste a decisão de opt-in automaticamente, então você não precisa chamar optIn() depois.
• init() lança exceção apenas quando configurationKey está vazio. Se o usuário não optou, ele registra e retorna silenciosamente. Caso contrário, ele abre um WebSocket para o backend do Mellowtel. A chamada não bloqueia a UI do renderizador, então as janelas permanecem responsivas enquanto a conexão é estabelecida.

​

Prevenindo interrupções de diálogos do sistema (recomendado)

​

Consentimento do Usuário

1. Use o diálogo nativo embutido via requestConsent(window, incentive). Este é o caminho mais rápido e é o que o snippet acima mostra. Ele renderiza um dialog.showMessageBox nativo do Electron com sua cópia de incentivo como título e persiste a decisão do usuário automaticamente.
2. Construa sua própria UI de consentimento e controle o SDK através de optIn(), optOut(), e getOptInStatus(). Use isso se você quiser personalização de marca, explicações mais ricas, ou localização além do que o diálogo nativo oferece.

​

O que seu diálogo de consentimento deve incluir

​

Permitir que os usuários alterem seu consentimento posteriormente

​

Referência de Métodos

• init(): Promise<void> inicia o serviço se o usuário optou, ou retorna silenciosamente cedo se não. Lança exceção apenas quando a chave de configuração está vazia.
• shutdown(): Promise<void> limpa os recursos do SDK quando o aplicativo está fechando. Fecha o WebSocket, destrói janelas de trabalho ocultas e limpa temporizadores de fundo. Preserva a preferência de opt-in do usuário.
• requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined> mostra o diálogo de consentimento nativo embutido e persiste o resultado. Retorna true ao aceitar, false ao recusar ou fechar, undefined se o consentimento já foi dado.
• showConsentSettings(window: BrowserWindow): Promise<void> mostra o diálogo de gerenciamento de consentimento embutido. O SDK lida com as transições de opt-in / opt-out internamente quando o usuário alterna sua escolha.

• optIn(): Promise<void> marca o usuário como optado sem mostrar um diálogo. Use isso apenas após coletar consentimento através da sua própria UI.
• optOut(): Promise<void> marca o usuário como não optado e realiza uma limpeza completa (mesmos recursos que shutdown(), além de limpar a preferência de consentimento salva). Não há necessidade de chamar shutdown() depois.
• getOptInStatus(): boolean | undefined retorna o estado atual de opt-in, ou undefined se o usuário nunca fez uma escolha.
• getNodeId(): string retorna o identificador de nó do Mellowtel para esta instalação. Útil ao registrar tickets de suporte.

• getTotalRequestCount(): number retorna o total de requisições processadas desde a instalação.
• getDailyRequestCount(): number retorna o número de requisições processadas hoje.
• getRequestCountForDate(date: string): number retorna a contagem para uma data específica YYYY-MM-DD.
• getDailyRequestsHistory(): { [date: string]: number } retorna cada contagem diária como um mapa.
• getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number } retorna contagens para um intervalo de datas.
• getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } } retorna todos os três contadores em uma chamada.

​

Ciclo de Vida e Encerramento do App

• Fecha a conexão WebSocket.
• Destrói janelas de trabalho ocultas.
• Limpa temporizadores de fundo e recursos de rede.
• Preserva a preferência de opt-in do usuário.

​

Aplicativos de janela única

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

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

​

Aplicativos de bandeja

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

​

Aplicativos macOS

​

Optando por sair

await mellowtel.optOut();

​

Iniciando novamente

await mellowtel.optIn(); // Apenas necessário após optOut()
await mellowtel.init();

​

Persistência de Consentimento

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

​

Solução de Problemas