Integra Mellowtel nella tua app desktop Windows

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’eccezione InvalidOperationException se chiami StartAsync() senza che l’utente abbia dato il consenso.

Prerequisiti

Un account Mellowtel e un ID di Integrazione dal dashboard. Ogni app desktop riceve un proprio 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, interruttore nelle impostazioni e ciclo di vita in background.

Installazione

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

1. Installa il Pacchetto

Dal tuo directory di 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à dato il consenso, riprendi silenziosamente.
// Altrimenti, non fa nulla e restituisce false.
await mellowtel.StartIfOptedInAsync();

// Flusso per la prima volta: mostra la tua UI di consenso, poi dai il consenso 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 permette 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 dare il consenso 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 già dato il consenso. 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 già dato il consenso. 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 viene attivato ogni volta che il WebSocket sottostante al backend di Mellowtel si connette o 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 viene attivato su un thread in background, quindi i framework UI che applicano l’affinità dei 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 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’eccezione InvalidOperationException se l’utente non ha dato il consenso.

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 annullare in qualsiasi momento nelle impostazioni.”

Dai agli utenti una scelta chiara

Includi opzioni distinte di Accetta e Rifiuta.

Collega alle politiche

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

Permetti agli utenti di cambiare il loro consenso nelle impostazioni

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

// Annulla il consenso
if (userWantsToOptOut)
{
    mellowtel.OptOut();
    await mellowtel.StopAsync();
}

// Riconferma il consenso
if (userWantsToOptIn)
{
    mellowtel.OptIn();
    await mellowtel.StartAsync();
}

Per un’interfaccia utente più ricca (ad esempio, mostrando quando l’utente ha dato il consenso per la prima volta), GetOptInDetails() restituisce lo stato del consenso insieme ai timestamp di consenso e revoca:

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.
Pulisci 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 una ripresa silenziosa nei lanci successivi, usa StartIfOptedInAsync() invece, che non fa nulla quando l’utente non ha dato il consenso.

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

Inizia

Concetti

App desktop

Plugin del browser

Sito web

App mobile

Integra Mellowtel nella tua app desktop Windows

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 cambiare il loro consenso nelle impostazioni

Risoluzione dei Problemi

Inizia

Concetti

App desktop

Plugin del browser

Sito web

App mobile

Documentation Index

​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 cambiare 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 cambiare il loro consenso nelle impostazioni

Risoluzione dei Problemi