Посібник з інтеграції Mellowtel у Windows .NET Desktop App

Інтегруйте Mellowtel у ваш додаток для Windows, щоб дозволити користувачам ділитися невикористаною пропускною здатністю інтернету в обмін на винагороди або преміум-функції.

Згода користувача є обов’язковою. SDK викидає InvalidOperationException, якщо ви викликаєте StartAsync() без того, щоб користувач погодився.

Попередні вимоги

Обліковий запис Mellowtel та Integration ID з панелі керування. Кожен додаток отримує свій унікальний Integration ID.
.NET 10 SDK
Windows 10 або Windows 11
Додаток на .NET (Console, WPF або Windows Forms)

Хочете побачити повну інтеграцію в реальному світі перед тим, як підключити це до свого додатку? Зразок mellowtel-pomodoro-windows для WPF показує повний потік від початку до кінця: діалог згоди, перемикач налаштувань та фоновий життєвий цикл.

Встановлення

Mellowtel для Windows доступний на NuGet як Mellowtel.Win.

1. Встановіть пакет

З вашої директорії проекту:

dotnet add package Mellowtel.Win

Або додайте PackageReference до вашого .csproj:

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

2. Додайте до вашого коду

using MellowtelWin;

// Ініціалізуйте Mellowtel з вашим Integration ID
var mellowtel = new Mellowtel("YOUR_INTEGRATION_ID", new MellowtelOptions
{
    PluginId = "your-app-id"
});

// Якщо користувач вже погодився, відновіть роботу без повідомлення.
// Якщо ні, це нічого не робить і повертає false.
await mellowtel.StartIfOptedInAsync();

// Потік для першого запуску: покажіть свій інтерфейс згоди, потім погодьтеся і почніть.
if (!mellowtel.GetOptInStatus() && ShowConsentDialog())
{
    mellowtel.OptIn();
    await mellowtel.StartAsync();
}

// При завершенні роботи додатку
await mellowtel.StopAsync();
mellowtel.Dispose();

Замініть YOUR_INTEGRATION_ID на Integration ID з вашої панелі керування Mellowtel, і встановіть PluginId як стабільний ідентифікатор для вашого додатку. ShowConsentDialog() — це ваш власний інтерфейс, який повертає true тільки тоді, коли користувач явно погоджується. Дивіться Згода користувача нижче.

Опції конфігурації

MellowtelOptions дозволяє налаштувати кілька параметрів:

Властивість	Тип	За замовчуванням	Опис
`PluginId`	`string`	`"mellowtel-win"`	Стабільний ідентифікатор для вашого додатку. Встановіть це на щось унікальне.
`MaxDailyRate`	`int`	Вбудоване значення за замовчуванням	Максимальна кількість запитів, які SDK обробляє за день.
`DisableLogs`	`bool`	`true`	Встановіть `false`, щоб увімкнути журнали SDK під час розробки.

Приклади за типом додатку

Консольний додаток
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("Користувач повинен погодитися перед використанням цієї служби.");
            return;
        }

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

        try
        {
            await mellowtel.StartAsync(cts.Token);
            Console.WriteLine("Mellowtel працює. Натисніть Ctrl+C, щоб зупинити.");
            await Task.Delay(Timeout.Infinite, cts.Token);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine($"Не можна запустити: {ex.Message}");
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Зупинка...");
        }
        finally
        {
            await mellowtel.StopAsync();
        }
    }
}

Додайте до вашого 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 ? "Підключено" : "Відключено";
            });
        };

        // Відновіть роботу без повідомлення, якщо вже погоджено. Інакше покажіть свій інтерфейс згоди.
        var started = await _mellowtel.StartIfOptedInAsync();
        if (!started)
        {
            // Покажіть свій діалог згоди тут
        }
    }

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

Додайте до вашого 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 ? "Підключено" : "Відключено");
            else
                statusLabel.Text = connected ? "Підключено" : "Відключено";
        };

        // Відновіть роботу без повідомлення, якщо вже погоджено. Інакше покажіть свій інтерфейс згоди.
        var started = await _mellowtel.StartIfOptedInAsync();
        if (!started)
        {
            // Покажіть свій діалог згоди тут
        }
    }

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

Спостереження за станом підключення

Екземпляр Mellowtel надає подію ConnectionStateChanged, яка викликається щоразу, коли підключення WebSocket до бекенду Mellowtel підключається або відключається. Приклади для WPF та Windows Forms вище підписуються на цю подію, щоб керувати індикатором стану. Навантаження — це bool, де true означає підключено, а false означає відключено. Подія викликається у фоновому потоці, тому UI-фреймворки, які забезпечують прив’язку до потоку, повинні передавати оновлення на UI-потік. У WPF використовуйте Dispatcher.Invoke, а в Windows Forms використовуйте Control.Invoke (обидва показані у прикладах вище).

Про WPF async void OnClosing патерн. Приклад WPF вище використовує protected override async void OnClosing, що є найпростішою формою, але має тонку проблему: base.OnClosing(e) викликається синхронно, поки StopAsync() ще очікує, тому вікно може закритися до завершення очищення. Для більшості додатків це нормально, оскільки процес завершується відразу після цього. Якщо вам потрібне гарантоване плавне завершення (наприклад, щоб зберегти телеметрію), дотримуйтесь документованого Microsoft патерну відкладення, де ви встановлюєте e.Cancel = true, await вашої асинхронної роботи, а потім явно закриваєте вікно.

Згода користувача

Відображення діалогу згоди є обов’язковим. SDK це забезпечує: StartAsync() викидає InvalidOperationException, якщо користувач не погодився.

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

if (!mellowtel.GetOptInStatus())
{
    var userAgreed = ShowConsentDialog(); // ваш власний діалог

    if (userAgreed)
        mellowtel.OptIn();
    else
        return; // користувач відмовився, не починайте
}

try
{
    await mellowtel.StartAsync();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Помилка: {ex.Message}");
}

Що має включати ваш діалог згоди

Поясніть, що робить Mellowtel

Використовуйте просту мову. Приклад: “Цей додаток використовує Mellowtel для обміну вашою невикористаною пропускною здатністю інтернету. Це дозволяє вам [користь/функція]. Ви можете відмовитися в будь-який час у налаштуваннях.”

Надайте користувачам чіткий вибір

Включіть окремі варіанти Прийняти та Відхилити.

Посилання на політики

Включіть посилання на Умови використання та Політику конфіденційності.

Дозвольте користувачам змінювати свою згоду в налаштуваннях

// Перевірте поточний статус
bool isOptedIn = mellowtel.GetOptInStatus();

// Відмова
if (userWantsToOptOut)
{
    mellowtel.OptOut();
    await mellowtel.StopAsync();
}

// Повернення згоди
if (userWantsToOptIn)
{
    mellowtel.OptIn();
    await mellowtel.StartAsync();
}

Для більш багатого інтерфейсу (наприклад, показуючи, коли користувач вперше погодився), GetOptInDetails() повертає статус згоди разом з датами згоди та відмови:

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

Усунення несправностей

Помилка "Пакет не знайдено"

Переконайтеся, що ваш проект націлений на .NET 10 або пізнішу версію. Mellowtel.Win вимагає net10.0.
Очистіть кеш NuGet і відновіть:

dotnet nuget locals all --clear
dotnet restore

Помилка "InvalidOperationException: Користувач не погодився"

StartAsync() вимагає явної згоди. Викличте OptIn() після того, як ваш діалог згоди поверне позитивний результат, потім викличте StartAsync(). Для безмовного відновлення при наступних запусках використовуйте StartIfOptedInAsync(), що нічого не робить, коли користувач не погодився.

Орієнтовний час завершення: 10-15 хвилин. Якщо вам потрібна допомога або у вас є відгуки, зв’яжіться з нами за адресою info@mellowtel.com або приєднуйтесь до нашої спільноти в Discord.

​Попередні вимоги

​Встановлення

​1. Встановіть пакет

​2. Додайте до вашого коду

​Опції конфігурації

​Приклади за типом додатку

​Спостереження за станом підключення

​Згода користувача

​Що має включати ваш діалог згоди

​Дозвольте користувачам змінювати свою згоду в налаштуваннях

​Усунення несправностей

Попередні вимоги

Встановлення

1. Встановіть пакет

2. Додайте до вашого коду

Опції конфігурації

Приклади за типом додатку

Спостереження за станом підключення

Згода користувача

Що має включати ваш діалог згоди

Дозвольте користувачам змінювати свою згоду в налаштуваннях

Усунення несправностей