> ## 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. # Guida all’Integrazione e al Consenso del Mellowtel Electron SDK > La configurazione del Mellowtel Electron SDK copre l’autenticazione del registro npm, l’installazione, i dialoghi di consenso, le impostazioni, i contatori delle richieste, il comportamento del ciclo di vita e la risoluzione dei problemi. Integra Mellowtel nella tua applicazione Electron multipiattaforma per consentire agli utenti di condividere la loro larghezza di banda internet inutilizzata in cambio di ricompense o funzionalità premium. L'SDK Electron funziona ovunque funzioni Electron (macOS, Windows e Linux). **Il consenso dell'utente è obbligatorio.** L'SDK opera solo quando l'utente ha esplicitamente acconsentito. `init()` ritorna silenziosamente in anticipo quando non c'è consenso registrato, quindi se vedi l'SDK avviarsi senza errori ma non inviare mai traffico, la ragione più probabile è che l'utente non ha ancora acconsentito. ## Prerequisiti * Un account Mellowtel e una chiave di configurazione (ottieni la tua dalla [dashboard](https://www.mellowtel.com/mellowtel-auth/)). * Un'applicazione Electron con accesso al processo principale. *** ## Installazione ### 1. Configura l'Autenticazione npm Crea un file `.npmrc` nella directory principale del tuo progetto per indirizzare npm al registro dei pacchetti GitHub di Mellowtel e autenticare l'installazione: ```bash theme={null} @mellowtel-inc:registry=https://npm.pkg.github.com/ //npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN ``` Sostituisci `YOUR_NPM_TOKEN` con il token di installazione qui sotto. Clicca per rivelarlo, quindi usa l'icona di copia sul blocco di codice per copiarlo negli appunti. ``` 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 ``` ### 2. Installa il Pacchetto Dalla radice del tuo progetto, installa l'SDK Electron: ```bash theme={null} npm install @mellowtel-inc/mellowtel-electron ``` ### 3. Aggiungi al Tuo Codice Nel file del processo principale di Electron (tipicamente `main.ts` o `main.js`), importa l'SDK, istanzialo con la tua chiave di configurazione, richiedi il consenso dall'utente, e poi chiama `init()` per avviare il servizio. ```typescript theme={null} import { app, BrowserWindow } from 'electron'; import Mellowtel from '@mellowtel-inc/mellowtel-electron'; // Quando l'app è pronta, crea la finestra app.whenReady().then(async () => { let win = createWindow(); const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY'); await mellowtel.requestConsent(win, "Ottieni 3 mesi gratis") await mellowtel.init() }); ``` Sostituisci `YOUR_CONFIGURATION_KEY` con la chiave dal tuo dashboard Mellowtel. **Cosa fa ciascuna chiamata:** * `new Mellowtel(configurationKey, options?)` istanzia l'SDK. L'unica opzione disponibile oggi è `disableLogs`, che di default è `true`. Impostalo su `false` durante l'integrazione per vedere lo stato della connessione e l'attività delle richieste nel tuo terminale. * `requestConsent(window, incentive)` rende una **finestra di messaggio nativa di Electron** ancorata al `BrowserWindow` che passi. Il secondo argomento è il titolo prominente del dialogo (ad esempio, `"Ottieni 3 mesi gratis"`), mostrato sopra una spiegazione fissa di cosa fa Mellowtel. Risolve a `true` se l'utente accetta, `false` se l'utente rifiuta o chiude il dialogo, e `undefined` se il consenso è già registrato. L'SDK persiste automaticamente la decisione di opt-in, quindi non è necessario chiamare `optIn()` successivamente. * `init()` lancia un'eccezione solo quando `configurationKey` è vuoto. Se l'utente non ha acconsentito, registra e ritorna silenziosamente. Altrimenti apre un WebSocket al backend di Mellowtel. La chiamata non blocca l'interfaccia utente del renderer, quindi le finestre rimangono reattive mentre la connessione viene stabilita. ### Prevenire interruzioni da dialoghi di sistema (consigliato) L'SDK viene fornito con un helper opzionale, `setupMellowtelApp()`, che configura i flag della riga di comando di Electron per sopprimere i dialoghi di sistema (popup di riempimento automatico, barre di traduzione, prompt di autenticazione NTLM / Kerberos, integrazione con il gestore di password, sovrapposizioni multimediali, dialoghi di prima esecuzione) che altrimenti interromperebbero i tuoi utenti quando le finestre nascoste di Mellowtel elaborano le richieste in background. Chiamalo all'inizio del tuo file di processo principale, **prima** di `app.whenReady()`, e importalo insieme all'esportazione predefinita da `@mellowtel-inc/mellowtel-electron`. Vedi il [README a monte](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional) per l'uso canonico. *** ## Consenso dell'Utente Mostrare un dialogo di consenso è **obbligatorio**. Devi permettere agli utenti di acconsentire esplicitamente prima di chiamare `init()`, e devi fornire un modo per gestire il loro stato di opt-in in qualsiasi momento. Hai due percorsi per gestire il consenso: 1. **Usa il dialogo nativo integrato** tramite `requestConsent(window, incentive)`. Questo è il percorso più veloce ed è quello mostrato nello snippet sopra. Rende un `dialog.showMessageBox` nativo di Electron con il tuo testo di incentivo come titolo e persiste automaticamente la decisione dell'utente. 2. **Costruisci la tua interfaccia di consenso** e gestisci l'SDK tramite `optIn()`, `optOut()`, e `getOptInStatus()`. Usa questo se vuoi personalizzare il branding, fornire spiegazioni più ricche, o localizzare oltre ciò che offre il dialogo nativo. ### Cosa deve includere il tuo dialogo di consenso Usa un linguaggio semplice. Esempio: *"Questa app utilizza Mellowtel per condividere la tua larghezza di banda internet inutilizzata. In cambio, ottieni \[beneficio/funzionalità]. Puoi rinunciare in qualsiasi momento nelle impostazioni."* Includi opzioni distinte per Accettare e Rifiutare. Includi link ai [Termini di Servizio](https://www.mellowtel.com/terms-and-conditions) e alla [Politica sulla Privacy](https://www.mellowtel.com/privacy-policy). ### Permetti agli utenti di cambiare il loro consenso in seguito Mellowtel fornisce un dialogo di impostazioni integrato tramite `showConsentSettings(window)`. Rende un dialogo nativo con pulsanti Opt In / Opt Out che corrispondono allo stato attuale dell'utente, e chiama internamente `optIn()` o `optOut()` (oltre a riconnettere il WebSocket su opt-in) quando l'utente cambia scelta. Collegalo a un elemento di menu o a un pulsante delle impostazioni nella tua app in modo che gli utenti possano rivedere la loro scelta. Se preferisci costruire il tuo schermo delle impostazioni, chiama `getOptInStatus()` per leggere lo stato attuale e `optIn()` / `optOut()` per cambiarlo. *** ## Riferimento ai Metodi La classe `Mellowtel` espone i seguenti metodi pubblici. Tutti sono disponibili sull'istanza creata con `new Mellowtel(configurationKey, options?)`. **Ciclo di vita** * `init(): Promise` avvia il servizio se l'utente ha acconsentito, o ritorna silenziosamente in anticipo se non lo ha fatto. Lancia un'eccezione solo quando la chiave di configurazione è vuota. * `requestConsent(window: BrowserWindow, incentive: string): Promise` mostra il dialogo di consenso nativo integrato e persiste il risultato. Ritorna `true` su accettazione, `false` su rifiuto o chiusura, `undefined` se il consenso era già stato dato. * `showConsentSettings(window: BrowserWindow): Promise` mostra il dialogo integrato per gestire il consenso. L'SDK gestisce internamente le transizioni di opt-in / opt-out quando l'utente cambia la propria scelta. **Controllo manuale dell'opt-in** * `optIn(): Promise` segna l'utente come optato senza mostrare un dialogo. Usa questo solo dopo aver raccolto il consenso tramite la tua interfaccia. * `optOut(): Promise` segna l'utente come optato fuori e chiude la connessione WebSocket attiva. * `getOptInStatus(): boolean | undefined` ritorna lo stato attuale di opt-in, o `undefined` se l'utente non ha mai fatto una scelta. * `getNodeId(): string` ritorna l'identificatore del nodo Mellowtel per questa installazione. Utile quando si presentano ticket di supporto. **Contatori delle richieste** I conteggi delle richieste sono persistiti localmente tramite `electron-store` e sopravvivono ai riavvii dell'app. Mostrali nella tua interfaccia se vuoi mostrare agli utenti l'impatto del loro opt-in. * `getTotalRequestCount(): number` ritorna il totale delle richieste elaborate dall'installazione. * `getDailyRequestCount(): number` ritorna il numero di richieste elaborate oggi. * `getRequestCountForDate(date: string): number` ritorna il conteggio per una specifica data `YYYY-MM-DD`. * `getDailyRequestsHistory(): { [date: string]: number }` ritorna ogni conteggio giornaliero come una mappa. * `getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number }` ritorna i conteggi per un intervallo di date. * `getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } }` ritorna tutti e tre i contatori in una chiamata. *** ## Spegnimento e Ciclo di Vita L'SDK Electron **non** registra i propri gestori `before-quit` o `will-quit`. Quando il tuo processo Electron esce, la connessione WebSocket in background viene smantellata con esso, e non è richiesta una pulizia esplicita da parte tua. Se vuoi disconnettere Mellowtel a metà sessione (ad esempio, quando un utente attiva un'impostazione di "pausa" nella tua app), chiama `optOut()`. Questo cancella sia il flag di opt-in che chiude la connessione attiva. Per riconnettersi, chiama `optIn()` seguito da `init()`. ## Persistenza del Consenso Lo stato di opt-in è memorizzato nel percorso di configurazione predefinito della piattaforma `electron-store`: * macOS: `~/Library/Application Support//config.json` * Windows: `%APPDATA%\\config.json` * Linux: `~/.config//config.json` Lo stato sopravvive agli aggiornamenti dell'app. Disinstallare la tua app non lo cancellerà automaticamente a meno che il tuo disinstallatore non rimuova esplicitamente la directory di configurazione dell'app. *** ## Risoluzione dei Problemi 1. Verifica che `.npmrc` sia nella radice del progetto, accanto al tuo `package.json`. 2. Assicurati che il token non abbia spazi bianchi iniziali o finali. 3. Cancella la cache npm e riprova eseguendo `npm cache clean --force` seguito da `npm install`. 1. Verifica che il token in `.npmrc` sia corretto e attivo. Se non sei sicuro, richiedi un nuovo token da [info@mellowtel.com](mailto:info@mellowtel.com). 2. Conferma che la linea `@mellowtel-inc:registry` sia presente e punti a `https://npm.pkg.github.com/`. 1. Assicurati di chiamare `requestConsent` **dopo** che `app.whenReady()` è stato risolto e con un riferimento `BrowserWindow` valido e non distrutto. 2. Se usi `setupMellowtelApp()`, verifica che sia chiamato **prima** di `app.whenReady()`, non dopo. Questo è progettato così. `init()` ritorna silenziosamente in anticipo quando l'utente non ha acconsentito. Controlla `getOptInStatus()` per confermare. Se ritorna `undefined` o `false`, esegui prima `requestConsent`. Nota che il log interno "User is not opted in" è ignorato quando `disableLogs` è lasciato al suo valore predefinito (vedi "Logs are silent" sotto), quindi il terminale non ti dà alcun segnale finché non cambi quel flag. L'opzione del costruttore `disableLogs` di default è `true`. Passa `{ disableLogs: false }` come secondo argomento al costruttore durante l'integrazione per visualizzare lo stato della connessione e l'attività delle richieste nel tuo terminale. Questo è anche il modo più veloce per distinguere un "not opted in" silenzioso da un vero fallimento di connessione. *** Tempo stimato per completare: 10-15 minuti. Se hai bisogno di aiuto o hai feedback, contattaci a [info@mellowtel.com](mailto:info@mellowtel.com) o unisciti alla nostra [comunità Discord](https://discord.com/invite/txAZp4MSDe).