Guida all’integrazione di Mellowtel per app desktop Windows .NET

Integra Mellowtel nella tua applicazione desktop Windows per consentire agli utenti di condividere la loro larghezza di banda internet inutilizzata in cambio di ricompense o funzionalità premium.

Il consenso dell’utente è obbligatorio. L’SDK genera un InvalidOperationException se chiami StartAsync() senza che l’utente abbia effettuato l’opt-in.

Prerequisiti

Un account Mellowtel e un ID di integrazione dal dashboard. Ogni app desktop riceve un ID di integrazione unico.
.NET 10 SDK
Windows 10 o Windows 11
Un’applicazione desktop .NET (Console, WPF o Windows Forms)

Vuoi vedere un’integrazione completa e reale prima di integrarla nella tua app? Il campione WPF mellowtel-pomodoro-windows mostra l’intero flusso dall’inizio alla fine: dialogo di consenso, attivazione delle impostazioni e ciclo di vita in background.

Installazione

Mellowtel per Windows è disponibile su NuGet come Mellowtel.Win.

1. Installa il pacchetto

Dalla directory del tuo progetto:

dotnet add package Mellowtel.Win

Oppure aggiungi un PackageReference al tuo .csproj:

<PackageReference Include="Mellowtel.Win" Version="1.0.0" />

2. Aggiungi al tuo codice

using MellowtelWin;

// Inizializza Mellowtel con il tuo ID di integrazione
var mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
{
    PluginId = "your-app-id"
});

// Se l'utente ha già effettuato l'opt-in, riprendi silenziosamente.
// In caso contrario, questa operazione non ha effetto e restituisce false.
await mellowtel.StartIfOptedInAsync();

// Flusso per la prima volta: mostra la tua UI di consenso, poi effettua l'opt-in e avvia.
if (!mellowtel.GetOptInStatus() && ShowConsentDialog())
{
    mellowtel.OptIn();
    await mellowtel.StartAsync();
}

// Alla chiusura dell'app
await mellowtel.StopAsync();
mellowtel.Dispose();

Sostituisci YOUR_INTEGRATION_ID con l’ID di integrazione dal tuo dashboard Mellowtel e imposta PluginId su un identificatore stabile per la tua app. ShowConsentDialog() è la tua UI personalizzata che restituisce true solo quando l’utente accetta esplicitamente. Vedi Consenso dell’utente qui sotto.

Opzioni di configurazione

MellowtelOptions ti consente di regolare alcune cose:

Proprietà	Tipo	Predefinito	Descrizione
`PluginId`	`string`	`"mellowtel-win"`	Identificatore stabile per la tua app. Impostalo su qualcosa di unico.
`MaxDailyRate`	`int`	Predefinito integrato	Numero massimo di richieste che l’SDK gestirà al giorno.
`DisableLogs`	`bool`	`true`	Imposta su `false` per abilitare i log dell’SDK durante lo sviluppo.

Esempi per tipo di applicazione

App Console
App WPF
Windows Forms

using MellowtelWin;

class Program
{
    static async Task Main(string[] args)
    {
        using var mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
        {
            PluginId = "your-app-id"
        });

        if (!mellowtel.GetOptInStatus())
        {
            Console.WriteLine("L'utente deve effettuare l'opt-in prima di utilizzare questo servizio.");
            return;
        }

        using var cts = new CancellationTokenSource();
        Console.CancelKeyPress += (s, e) => { e.Cancel = true; cts.Cancel(); };

        try
        {
            await mellowtel.StartAsync(cts.Token);
            Console.WriteLine("Mellowtel in esecuzione. Premi Ctrl+C per fermare.");
            await Task.Delay(Timeout.Infinite, cts.Token);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine($"Impossibile avviare: {ex.Message}");
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Arresto in corso...");
        }
        finally
        {
            await mellowtel.StopAsync();
        }
    }
}

Aggiungi al tuo MainWindow.xaml.cs:

using MellowtelWin;
using System.Windows;

public partial class MainWindow : Window
{
    private Mellowtel? _mellowtel;

    public MainWindow()
    {
        InitializeComponent();
        Loaded += Window_Loaded;
    }

    private async void Window_Loaded(object sender, RoutedEventArgs e)
    {
        _mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
        {
            PluginId = "your-app-id"
        });

        _mellowtel.ConnectionStateChanged += (s, connected) =>
        {
            Dispatcher.Invoke(() =>
            {
                StatusTextBlock.Text = connected ? "Connesso" : "Disconnesso";
            });
        };

        // Riprendi silenziosamente se hai già effettuato l'opt-in. Altrimenti mostra la tua UI di consenso.
        var started = await _mellowtel.StartIfOptedInAsync();
        if (!started)
        {
            // Mostra qui il tuo dialogo di consenso
        }
    }

    protected override async void OnClosing(CancelEventArgs e)
    {
        if (_mellowtel != null)
        {
            await _mellowtel.StopAsync();
            _mellowtel.Dispose();
        }
        base.OnClosing(e);
    }
}

Aggiungi al tuo MainForm.cs:

using MellowtelWin;

public partial class MainForm : Form
{
    private Mellowtel? _mellowtel;

    public MainForm()
    {
        InitializeComponent();
        Load += MainForm_Load;
        FormClosing += MainForm_FormClosing;
    }

    private async void MainForm_Load(object sender, EventArgs e)
    {
        _mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
        {
            PluginId = "your-app-id"
        });

        _mellowtel.ConnectionStateChanged += (s, connected) =>
        {
            if (InvokeRequired)
                Invoke(() => statusLabel.Text = connected ? "Connesso" : "Disconnesso");
            else
                statusLabel.Text = connected ? "Connesso" : "Disconnesso";
        };

        // Riprendi silenziosamente se hai già effettuato l'opt-in. Altrimenti mostra la tua UI di consenso.
        var started = await _mellowtel.StartIfOptedInAsync();
        if (!started)
        {
            // Mostra qui il tuo dialogo di consenso
        }
    }

    private async void MainForm_FormClosing(object sender, FormClosingEventArgs e)
    {
        if (_mellowtel != null)
        {
            await _mellowtel.StopAsync();
            _mellowtel.Dispose();
        }
    }
}

Osservare lo stato della connessione

L’istanza Mellowtel espone un evento ConnectionStateChanged che si attiva ogni volta che il WebSocket sottostante al backend di Mellowtel si connette o si disconnette. Gli esempi WPF e Windows Forms sopra si iscrivono a questo evento per gestire un indicatore di stato. Il payload è un bool dove true significa connesso e false significa disconnesso. L’evento si attiva su un thread in background, quindi i framework UI che applicano l’affinità del thread devono trasferire gli aggiornamenti sul thread UI. In WPF usa Dispatcher.Invoke, e in Windows Forms usa Control.Invoke (entrambi mostrati negli esempi sopra).

A proposito del pattern WPF async void OnClosing. L’esempio WPF sopra utilizza protected override async void OnClosing, che è la forma più semplice ma ha un problema sottile: base.OnClosing(e) viene chiamato in modo sincrono mentre StopAsync() è ancora in attesa, quindi la finestra può chiudersi prima che la pulizia sia terminata. Per la maggior parte delle app questo va bene perché il processo termina immediatamente dopo. Se hai bisogno di una chiusura garantita e ordinata (ad esempio, per inviare telemetria), segui il pattern di differimento documentato da Microsoft dove imposti e.Cancel = true, await il tuo lavoro asincrono, e poi chiudi esplicitamente la finestra.

Consenso dell’utente

Mostrare un dialogo di consenso è obbligatorio. L’SDK lo impone: StartAsync() genera un InvalidOperationException se l’utente non ha effettuato l’opt-in.

var mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
{
    PluginId = "your-app-id"
});

if (!mellowtel.GetOptInStatus())
{
    var userAgreed = ShowConsentDialog(); // il tuo dialogo personalizzato

    if (userAgreed)
        mellowtel.OptIn();
    else
        return; // l'utente ha rifiutato, non avviare
}

try
{
    await mellowtel.StartAsync();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Errore: {ex.Message}");
}

Cosa deve includere il tuo dialogo di consenso

Spiega cosa fa Mellowtel

Usa un linguaggio semplice. Esempio: “Questa app utilizza Mellowtel per condividere la tua larghezza di banda internet inutilizzata. Questo ti permette di [beneficio/funzionalità]. Puoi disattivare in qualsiasi momento nelle impostazioni.”

Dai agli utenti una scelta chiara

Includi opzioni distinte per Accettare e Rifiutare.

Collega alle politiche

Includi link ai Termini di servizio e alla Politica sulla privacy.

Permetti agli utenti di modificare il loro consenso nelle impostazioni

// Controlla lo stato attuale
bool isOptedIn = mellowtel.GetOptInStatus();

// Effettua l'opt-out
if (userWantsToOptOut)
{
    mellowtel.OptOut();
    await mellowtel.StopAsync();
}

// Effettua nuovamente l'opt-in
if (userWantsToOptIn)
{
    mellowtel.OptIn();
    await mellowtel.StartAsync();
}

Per una UI più ricca (ad esempio, mostrando quando l’utente ha effettuato l’opt-in per la prima volta), GetOptInDetails() restituisce lo stato di opt-in insieme ai timestamp di opt-in e opt-out:

var (isOptedIn, optInDate, optOutDate) = mellowtel.GetOptInDetails();

Risoluzione dei problemi

Errore "Pacchetto non trovato"

Assicurati che il tuo progetto sia destinato a .NET 10 o successivo. Mellowtel.Win richiede net10.0.
Cancella la cache di NuGet e ripristina:

dotnet nuget locals all --clear
dotnet restore

Errore "InvalidOperationException: User has not opted in"

StartAsync() richiede un consenso esplicito. Chiama OptIn() dopo che il tuo dialogo di consenso restituisce un risultato positivo, quindi chiama StartAsync(). Per un ripristino silenzioso nei lanci successivi, usa StartIfOptedInAsync(), che non ha effetto quando l’utente non ha effettuato l’opt-in.

Tempo stimato per completare: 10-15 minuti. Se hai bisogno di aiuto o vuoi inviare feedback, contattaci a info@mellowtel.com o unisciti alla nostra comunità Discord.

​Prerequisiti

​Installazione

​1. Installa il pacchetto

​2. Aggiungi al tuo codice

​Opzioni di configurazione

​Esempi per tipo di applicazione

​Osservare lo stato della connessione

​Consenso dell’utente

​Cosa deve includere il tuo dialogo di consenso

​Permetti agli utenti di modificare il loro consenso nelle impostazioni

​Risoluzione dei problemi

Prerequisiti

Installazione

1. Installa il pacchetto

2. Aggiungi al tuo codice

Opzioni di configurazione

Esempi per tipo di applicazione

Osservare lo stato della connessione

Consenso dell’utente

Cosa deve includere il tuo dialogo di consenso

Permetti agli utenti di modificare il loro consenso nelle impostazioni

Risoluzione dei problemi