> ## 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. # Integre o Mellowtel no seu App Electron Integre o Mellowtel no seu aplicativo Electron multiplataforma para permitir que os usuários compartilhem sua largura de banda de internet não utilizada em troca de recompensas ou recursos premium. O SDK do Electron funciona em qualquer lugar onde o Electron é executado (macOS, Windows e Linux). **O consentimento do usuário é obrigatório.** O SDK só opera quando o usuário optou explicitamente. `init()` retorna silenciosamente cedo quando não há consentimento registrado, então se você ver o SDK iniciar sem erros, mas nunca enviar tráfego, a razão mais provável é que o usuário ainda não optou. ## Pré-requisitos * Uma conta Mellowtel e chave de configuração (obtenha a sua no [painel de controle](https://www.mellowtel.com/mellowtel-auth/)). * Um aplicativo Electron com acesso ao processo principal. *** ## Instalação ### 1. Configurar Autenticação npm Crie um arquivo `.npmrc` no diretório raiz do seu projeto para apontar o npm para o registro de Pacotes GitHub do Mellowtel e autenticar a instalação: ```bash theme={null} @mellowtel-inc:registry=https://npm.pkg.github.com/ //npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN ``` Substitua `YOUR_NPM_TOKEN` pelo token de instalação abaixo. Clique para revelar, depois use o ícone de cópia no bloco de código para copiá-lo para sua área de transferência. ``` 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 ``` ### 2. Instalar o Pacote Do diretório raiz do seu projeto, instale o SDK do Electron: ```bash theme={null} npm install @mellowtel-inc/mellowtel-electron ``` ### 3. Adicionar ao Seu Código No arquivo de processo principal do seu Electron (geralmente `main.ts` ou `main.js`), importe o SDK, instancie-o com sua chave de configuração, solicite consentimento do usuário e, em seguida, chame `init()` para iniciar o serviço. ```typescript theme={null} import { app, BrowserWindow } from 'electron'; import Mellowtel from '@mellowtel-inc/mellowtel-electron'; // 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() }); ``` Substitua `YOUR_CONFIGURATION_KEY` pela chave do seu painel de controle Mellowtel. **O que cada chamada faz:** * `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 que você possa ver o estado da conexão e a atividade de solicitações no seu terminal. * `requestConsent(window, incentive)` renderiza uma **caixa de mensagem nativa do Electron** ancorada na `BrowserWindow` que você passar. 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) O SDK vem com um auxiliar opcional, `setupMellowtelApp()`, que configura flags de linha de comando do Electron para suprimir diálogos do sistema (pop-ups de preenchimento automático, barras de tradução, prompts de autenticação NTLM / Kerberos, integração com gerenciadores de senha, sobreposições de mídia, diálogos de primeira execução) que, de outra forma, interromperiam seus usuários quando as janelas ocultas do Mellowtel processam solicitações em segundo plano. Chame-o no topo do seu arquivo de processo principal, **antes** de `app.whenReady()`, e importe-o juntamente com a exportação padrão de `@mellowtel-inc/mellowtel-electron`. Veja o [README original](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional) para o uso canônico. *** ## Consentimento do Usuário Exibir um diálogo de consentimento é **obrigatório**. Você deve permitir que os usuários optem explicitamente antes de chamar `init()`, e deve fornecer uma maneira para eles gerenciarem seu estado de opt-in a qualquer momento. Você tem dois caminhos para lidar com o consentimento: 1. **Use o diálogo nativo embutido** via `requestConsent(window, incentive)`. Este é o caminho mais rápido e é o que o trecho acima mostra. Ele renderiza um `dialog.showMessageBox` nativo do Electron com seu texto 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 Use linguagem simples. Exemplo: *"Este app usa o Mellowtel para compartilhar sua largura de banda de internet não utilizada. Em troca, você recebe \[benefício/recurso]. Você pode optar por sair a qualquer momento nas configurações."* Inclua opções distintas de Aceitar e Recusar. Inclua links para os [Termos de Serviço](https://www.mellowtel.com/terms-and-conditions) e [Política de Privacidade](https://www.mellowtel.com/privacy-policy). ### Permitir que os usuários alterem seu consentimento posteriormente O Mellowtel fornece um diálogo de configurações embutido via `showConsentSettings(window)`. Ele renderiza um diálogo nativo com botões de Opt In / Opt Out que correspondem ao estado atual do usuário, e internamente chama `optIn()` ou `optOut()` (além de reconectar o WebSocket no opt-in) quando o usuário alterna. Conecte-o a um item de menu ou botão de configurações no seu app para que os usuários possam revisar sua escolha. Se você preferir construir sua própria tela de configurações, chame `getOptInStatus()` para ler o estado atual e `optIn()` / `optOut()` para alterá-lo. *** ## Referência de Métodos A classe `Mellowtel` expõe os seguintes métodos públicos. Todos estão disponíveis na instância que você criou com `new Mellowtel(configurationKey, options?)`. **Ciclo de Vida** * `init(): Promise` 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. * `requestConsent(window: BrowserWindow, incentive: string): Promise` 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` mostra o diálogo embutido de gerenciamento de consentimento. O SDK lida com as transições de opt-in / opt-out internamente quando o usuário alterna sua escolha. **Controle manual de opt-in** * `optIn(): Promise` 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` marca o usuário como optado para fora e fecha a conexão WebSocket ativa. * `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 abrir tickets de suporte. **Contadores de Solicitações** As contagens de solicitações são persistidas localmente através do `electron-store` e sobrevivem a reinicializações do app. Exiba-as na sua própria UI se quiser mostrar aos usuários o impacto do seu opt-in. * `getTotalRequestCount(): number` retorna o total de solicitações processadas desde a instalação. * `getDailyRequestCount(): number` retorna o número de solicitaçõ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 única chamada. *** ## Desligamento e Ciclo de Vida O SDK do Electron **não** registra seus próprios manipuladores `before-quit` ou `will-quit`. Quando seu processo Electron sai, a conexão WebSocket em segundo plano é encerrada com ele, e nenhuma limpeza explícita é necessária do seu lado. Se você quiser desconectar o Mellowtel no meio da sessão (por exemplo, quando um usuário alterna uma configuração de "pausa" no seu app), chame `optOut()`. Isso limpa tanto o flag de opt-in quanto fecha a conexão ativa. Para reconectar, chame `optIn()` seguido de `init()`. ## Persistência de Consentimento O estado de opt-in é armazenado no caminho de configuração padrão da plataforma `electron-store`: * macOS: `~/Library/Application Support//config.json` * Windows: `%APPDATA%\\config.json` * Linux: `~/.config//config.json` O estado sobrevive a atualizações do app. Desinstalar seu app não o limpará automaticamente, a menos que seu desinstalador remova explicitamente o diretório de configuração do app. *** ## Solução de Problemas 1. Verifique se `.npmrc` está na raiz do projeto, ao lado do seu `package.json`. 2. Certifique-se de que o token não tenha espaços em branco no início ou no final. 3. Limpe o cache do npm e tente novamente executando `npm cache clean --force` seguido de `npm install`. 1. Verifique se o token em `.npmrc` está correto e ativo. Se você não tiver certeza, solicite um novo token em [info@mellowtel.com](mailto:info@mellowtel.com). 2. Confirme se a linha `@mellowtel-inc:registry` está presente e aponta para `https://npm.pkg.github.com/`. 1. Certifique-se de chamar `requestConsent` **após** `app.whenReady()` ter sido resolvido e com uma referência `BrowserWindow` válida e não destruída. 2. Se você usar `setupMellowtelApp()`, verifique se ele é chamado **antes** de `app.whenReady()`, não depois. Isso é por design. `init()` retorna silenciosamente cedo quando o usuário não optou. Verifique `getOptInStatus()` para confirmar. Se ele retornar `undefined` ou `false`, execute `requestConsent` primeiro. Note que o log interno "Usuário não optou" é suprimido quando `disableLogs` é deixado em seu padrão (veja "Logs estão silenciosos" abaixo), então o terminal não dá sinal de qualquer forma até você alterar esse flag. A opção de construtor `disableLogs` por padrão é `true`. Passe `{ disableLogs: false }` como o segundo argumento para o construtor durante a integração para exibir o estado da conexão e a atividade de solicitações no seu terminal. Este também é o jeito mais rápido de distinguir um "não optado" silencioso de uma falha real de conexão. *** Tempo estimado para completar: 10-15 minutos. Se precisar de ajuda ou tiver feedback, entre em contato conosco em [info@mellowtel.com](mailto:info@mellowtel.com) ou junte-se à nossa [comunidade no Discord](https://discord.com/invite/txAZp4MSDe).