Skip to main content
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).
  • 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:
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.

​
2. Installa il Pacchetto

Dalla radice del tuo progetto, installa l’SDK 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.
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 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

1

Spiega cosa fa Mellowtel

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.”
2

Dai agli utenti una scelta chiara

Includi opzioni distinte per Accettare e Rifiutare.
3

Collega alle politiche

Includi link ai Termini di Servizio e alla Politica sulla Privacy.

​
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<void> 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<boolean | undefined> 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<void> 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<void> segna l’utente come optato senza mostrare un dialogo. Usa questo solo dopo aver raccolto il consenso tramite la tua interfaccia.
  • optOut(): Promise<void> 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/<YourAppName>/config.json
  • Windows: %APPDATA%\<YourAppName>\config.json
  • Linux: ~/.config/<YourAppName>/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.
  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 o unisciti alla nostra comunità Discord.