# Наперед 1.0: Готовість до виробництва УмаміM SK1NET

<!-- category -- C#, Umami, Analytics, Open Source -->
<datetime class="hidden">2025-11-20T14:30</datetime>

## Введение

Коли я вперше [Аналітика Умамі](https://umami.is/) в мою блогову платформу, Я швидко потрапив у розчаровуючу реальність : UmamiM SK2s API документація є МSK3 дозволять МСК4 бути доброчинним і називати його М С К 5 мінімальний М S К 6 Сообщення про помилки є криптичними в найкращому випадку M С К 7 не ’ М С С К 8 ’ є в найгіршому випадку ’ M С K 9 ’ Параметри змінюються між версіями без попередження M S К 10 ’ І навіть не змусять мене почати на М С К 12 ’ бп боп ‘ М С K 13 ’ ботов реагування на виявлення роботів ’ Б С К 14 ’

Тож я створив [Umami.NET](https://github.com/scottgal/mostlylucidweb/tree/main/Umami.Net) - не просто як простий HTTP упаковник ,, а як продуктивна МSK2 готова клиентська бібліотека, яка компенсує всі недоліки Umami M SK3 . Як і Я MSC5 я працювала над МСК6 релізом М СК7 Я М סК8 зосередилася на трьох критичних галузях M СК9

1. **Комплексне перевірки з допомогою корисних повідомлень про помилки**
2. **Robust testing infrastructure**
3. **Милозливе подолання помилок для реальних сценаріїв -world**

Дозвольте мені показати вам, що робить цю бібліотеку продуктивною.

[![NuGet](https://img.shields.io/nuget/v/Umami.Net.svg?style=flat-square)](https://www.nuget.org/packages/Umami.Net/)
[![Ліцензія: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![.NET](https://img.shields.io/badge/.NET-9.0-purple?style=flat-square)](https://dotnet.microsoft.com/)

[TOC]

## Проблема: UmamiM SK1s Documentation Gap

Ось з чим ви зіткнулися під час роботи з API Umami

- **Нічого не підтверджує** - Посилати неправильне GUID? Беззвучний похибкаM SK2
- **Криптичні реакції** - Bot detectedM SK1 Ви отримуєте `"beep boop"`МSK0 Це ' це .
- **Перехилення змін** - Параметри переименовані між версіями `path` проти `url`, `hostname` проти `host`)
- **Заплутаність тайм-тамп** - Унікс-мілісекунди ? SekundіM SK2 Щиро дякую, що ви зрозуміли це.
- **Відповіді JWT** - Іноді повні вантажі , іноді просто ID для відвідувачів МSK2 Немає документів, які пояснюють, коли чи чому

Це добре для швидкого прототипу , але для виробництва? Вам потрібно щось кращеM SK2

## Клаузи охорони: Зазнають невдачі у контексті

Найгірші помилки - ті, що беззвучно зазнають невдачі.

### Проверка конфігурації

```csharp
public static void ValidateSettings(UmamiClientSettings settings)
{
    // Guard: UmamiPath is required
    if (string.IsNullOrEmpty(settings.UmamiPath))
        throw new ArgumentNullException(settings.UmamiPath,
            "UmamiUrl is required");

    // Guard: UmamiPath must be valid URI
    if (!Uri.TryCreate(settings.UmamiPath, UriKind.Absolute, out _))
        throw new FormatException(
            "UmamiUrl must be a valid Uri");

    // Guard: WebsiteId is required
    if (string.IsNullOrEmpty(settings.WebsiteId))
        throw new ArgumentNullException(settings.WebsiteId,
            "WebsiteId is required");

    // Guard: WebsiteId must be valid GUID
    if (!Guid.TryParseExact(settings.WebsiteId, "D", out _))
        throw new FormatException(
            "WebSiteId must be a valid Guid");
}
```

Це відбувається на початку вашого `Program.cs`. Якщо ваша конфігурація неправильнаM SK1 ви одразу ж знаєте - не тоді, коли перший аналізовий випадок намагається надіслати

### Вимагати перевірки з допоміжними підказками

Але справжня магія полягає в допомічникі строків запиту. Подивіться на ці повідомлення

```csharp
public static string ToQueryString(this object obj)
{
    if (obj == null)
    {
        throw new ArgumentNullException(nameof(obj),
            "Cannot convert null object to query string. " +
            "Suggestion: Ensure you create and populate a request object " +
            "before calling ToQueryString().");
    }

    foreach (var property in objectType.GetProperties())
    {
        if (attribute.IsRequired)
        {
            if (propertyValue == null)
            {
                throw new ArgumentException(
                    $"Required parameter '{propertyName}' " +
                    $"(property '{property.Name}') cannot be null. " +
                    $"Suggestion: Set the {property.Name} property " +
                    $"on your {objectType.Name} object...",
                    property.Name);
            }

            // For strings, check for empty/whitespace
            if (propertyValue is string strValue &&
                string.IsNullOrWhiteSpace(strValue))
            {
                throw new ArgumentException(
                    $"Required parameter '{propertyName}' " +
                    $"cannot be empty or whitespace. " +
                    $"Suggestion: Set {property.Name} to a valid non-empty value.",
                    property.Name);
            }
        }
    }
}
```

Зверніть увагу на `Suggestion:` prefix? Кожне повідомлення про помилку говорить вам **що пішло не так** і **як це виправити**. Це документація, яку мав би надати Умамі

### Проверка діапазону даних

При створенні аналітиких запитів, діапазони дати можуть бути складнимиM SK1 Бібліотека вловлює ці помилки для вас

```csharp
public DateTime StartAtDate
{
    get => _startAtDate;
    set
    {
        if (_endAtDate != default && value > _endAtDate)
        {
            throw new ArgumentException(
                $"StartAtDate ({value:O}) must be before EndAtDate ({_endAtDate:O}). " +
                "Suggestion: Set StartAtDate to an earlier date or adjust EndAtDate.",
                nameof(StartAtDate));
        }
        _startAtDate = value;
    }
}

public virtual void Validate()
{
    if (StartAtDate == default)
    {
        throw new InvalidOperationException(
            "StartAtDate is required. " +
            "Suggestion: Set StartAtDate to a valid date " +
            "(e.g., DateTime.UtcNow.AddDays(-7) for last 7 days).");
    }
}
```

## Обладнання помилками Умамі

### Проблема "Beep BoopM SK1

Умі's розпізнавання робота повертає просту текстову відповідь `"beep boop"`. Не JSONM SK1 Неправильний код статусу. ПростоMSC3 гейп-бопМSK4

Ось як обробляє його Umami, ., NET

```csharp
public async Task<UmamiDataResponse> DecodeResponse(HttpResponseMessage response)
{
    var responseString = await response.Content.ReadAsStringAsync();

    // Handle bot detection
    if (responseString.Contains("beep") && responseString.Contains("boop"))
    {
        logger.LogWarning("Bot detected - data not stored in Umami");
        return new UmamiDataResponse(ResponseStatus.BotDetected);
    }

    // Handle JWT response
    try
    {
        var jwtPayload = DecodeJwt(responseString);
        return new UmamiDataResponse(ResponseStatus.Success, jwtPayload);
    }
    catch (Exception e)
    {
        logger.LogError(e, "Failed to decode response");
        return new UmamiDataResponse(ResponseStatus.Failed);
    }
}
```

Ваш код отримує чистий енум:

```csharp
public enum ResponseStatus
{
    Failed,
    BotDetected,
    Success
}
```

Немає більше дивних відповідей для аналізу. - просто перевіряйте статус

### Зміни на ім 'я параметрів

Умамі переименував параметри між версіями API. Чи вони це документували? ? Звичайно, ні МSK2 Бібліотека обробляє їх обидва:

```csharp
// Support both old and new parameter names
request.Path = queryParams["path"] ?? queryParams["url"];
request.Hostname = queryParams["hostname"] ?? queryParams["host"];
```

### Перетворення на тайм-тамп

Умамі використовує Unix мілісекунд для тайм-тампів.

```csharp
public static long ToMilliseconds(this DateTime dateTime)
{
    var dateTimeOffset = new DateTimeOffset(dateTime.ToUniversalTime());
    return dateTimeOffset.ToUnixTimeMilliseconds();
}
```

Тепер ви можете працювати з нормою `DateTime` об 'єкти і дозволити бібліотеці виконувати конвертацію.

## Обробка фону з каналами

Аналітики ніколи не мають блокувати вашу програму. UmamiM SK1NET включає в себе відправника, який використовує `System.Threading.Channels`:

```csharp
public class UmamiBackgroundSender : IHostedService
{
    private readonly Channel<UmamiPayload> _channel;
    private readonly UmamiClient _client;

    public async Task Track(string eventName,
        string? url = null,
        UmamiEventData? data = null)
    {
        var payload = new UmamiPayload
        {
            Website = _settings.WebsiteId,
            Name = eventName,
            Url = url ?? string.Empty,
            Data = data
        };

        // Non-blocking write to channel
        await _channel.Writer.WriteAsync(payload);
    }

    private async Task ProcessQueue(CancellationToken stoppingToken)
    {
        await foreach (var payload in _channel.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                await _client.Send(payload);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to send event to Umami");
            }
        }
    }
}
```

Мери стоять в черзі в пам 'яті і обробляються асинхронно. Ваші веб-запити повертаються миттєвоM SK1 аналіз відбувається у фоні.

## Знову спробувати політику з Поллі

Спустошення мережі трапляється. Бібліотека використовує Polly для стійких HTTP дзвінків:

```csharp
public static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
    var delay = Backoff.DecorrelatedJitterBackoffV2(
        TimeSpan.FromSeconds(1),
        retryCount: 3);

    return HttpPolicyExtensions
        .HandleTransientHttpError()
        .OrResult(msg => msg.StatusCode == HttpStatusCode.ServiceUnavailable)
        .WaitAndRetryAsync(delay);
}
```

Перехідні невдачі та помилки 503 призводять до автоматичних повторів з експоненційним відхиленням . Ваша аналітика гнучка до тимчасових проблем з мережею МSK2

## Authentication with Auto-Retry

Коли вибираєте аналізні дані ( не просто надсилаєте подіїM SK1 вам потрібна аутентифікація . Бібліотека автоматизує виведення токенів

```csharp
public async Task<UmamiResult<StatsResponseModel>> GetStats(StatsRequest statsRequest)
{
    var response = await _httpClient.GetAsync(url);

    // Token expired? Re-authenticate and retry
    if (response.StatusCode == HttpStatusCode.Unauthorized)
    {
        await _authService.Login();
        return await GetStats(statsRequest); // Recursive retry
    }

    // Parse and return
    var content = await response.Content.ReadFromJsonAsync<StatsResponseModel>();
    return new UmamiResult<StatsResponseModel>(
        response.StatusCode,
        response.ReasonPhrase ?? string.Empty,
        content);
}
```

Вам ніколи не потрібно думати про управління токенами.

## Тестування інфраструктури

Produkція- готовий код потребує комплексних тестів . ТутM SK2 це те, що я збудував

### FakeLogger для перевірки журналу

Використовуючи Microsoft's `FakeLogger` пакет, тести можуть перевірити логінг

```csharp
[Fact]
public async Task Login_Success_LogsMessage()
{
    // Arrange
    var fakeLogger = new FakeLogger<AuthService>();
    var authService = new AuthService(httpClient, settings, fakeLogger);

    // Act
    await authService.Login();

    // Assert
    var logs = fakeLogger.Collector.GetSnapshot();
    Assert.Contains("Login successful", logs.Select(x => x.Message));
}
```

### Керівники HTTP Custom Mock

Випробовування асинхових операцій складно. `TaskCompletionSource`:

```csharp
[Fact]
public async Task BackgroundSender_ProcessesEventAsynchronously()
{
    var tcs = new TaskCompletionSource<bool>();

    var handler = EchoMockHandler.Create(async (message, token) =>
    {
        try
        {
            // Assert the request was sent correctly
            var payload = await message.Content.ReadFromJsonAsync<UmamiPayload>();
            Assert.Equal("test-event", payload.Name);

            tcs.SetResult(true); // Signal test completion
            return new HttpResponseMessage(HttpStatusCode.OK);
        }
        catch (Exception e)
        {
            tcs.SetException(e);
            return new HttpResponseMessage(HttpStatusCode.InternalServerError);
        }
    });

    // Track event
    await backgroundSender.Track("test-event");

    // Wait for background processing with timeout
    var completedTask = await Task.WhenAny(tcs.Task, Task.Delay(1000));
    if (completedTask != tcs.Task)
        throw new TimeoutException("Event was not processed within timeout");

    await tcs.Task; // Throw if assertions failed
}
```

Ця модель гарантує:

- Взагалі-то оброблені події
- Обробка закінчується в зручний час
- Вказівки у регулювальнику макетів надлежало повідомляти

### Комплексне тестування

Тестовий пакет obejmuje:

- ✅ Веріалізація конфігурації (неправильні GUIDsM SK2 бракуючих URLsМSK3
- ✅ Переслідування подій з і без даних
- ✅ Переслідування сторінки
- ✅ Identyfikacja користувача
- ✅ Рухування при виявленні Bot
- ✅ Кодування реакції JWT
- ✅ Обробка фону з перервами часу
- ✅ Validaція діапазону даних
- ✅ генерування строків запиту
- ✅ Аuthentication and token refresh
- ✅ Перетягування даних вимірів та сторінок

## Реальний- Світове використання

Ось як просто це використовувати в ASP

### Установка в програмі.cs

```csharp
builder.Services.SetupUmamiClient(builder.Configuration);
```

Що's itM SK1 Бібліотека читає ваші `appsettings.json`:

```json
{
  "Analytics": {
    "UmamiPath": "https://analytics.yoursite.com",
    "WebsiteId": "your-website-guid"
  }
}
```

### Відповіді про події

```csharp
public class HomeController : Controller
{
    private readonly UmamiBackgroundSender _umami;

    public HomeController(UmamiBackgroundSender umami)
    {
        _umami = umami;
    }

    public IActionResult Index()
    {
        // Non-blocking event tracking
        await _umami.TrackPageView("/", "Home Page");

        return View();
    }

    [HttpPost]
    public async Task<IActionResult> Subscribe(string email)
    {
        // Track with custom data
        await _umami.Track("newsletter-signup",
            data: new UmamiEventData
            {
                { "source", "homepage" },
                { "email_domain", email.Split('@')[1] }
            });

        return RedirectToAction("ThankYou");
    }
}
```

### Перейти до даних аналітики

```csharp
public class AnalyticsDashboardController : Controller
{
    private readonly IUmamiDataService _umamiData;

    public async Task<IActionResult> Stats()
    {
        var request = new StatsRequest
        {
            StartAtDate = DateTime.UtcNow.AddDays(-30),
            EndAtDate = DateTime.UtcNow
        };

        var result = await _umamiData.GetStats(request);

        if (result.Status == HttpStatusCode.OK)
        {
            var stats = result.Data;
            // stats.Visitors, stats.PageViews, stats.BounceRate, etc.
            return View(stats);
        }

        return View("Error");
    }
}
```

## Що Next for 1.0?

Бібліотека є функцією-повне та боєздатнаМSK1тестована в розробці на цьому самому блогіМСК2 Перед випуском MСК3 МСК4 ЯМ СК5 я зосереджуся наМSК6

- 📝 Комплексна документація API
- 🎯 Публикація пакетів NuGet
- 📊 Benchmarks Performance
- 🔧 Додаткові методи зручності для загальних аналізних запитів

## Завершення

Побудувати готову бібліотеку для виробництва - це не просто обгортання API, а створення такого досвіду. **краще** ніж безпосередньо використовувати API. NET compensates for Umami's documentation gaps with

- **Виновлення, яке пояснює, що пішло не так і як його виправити**
- **Гарний підхід до химерних API поведінки**
- **Комплексне тестування, яке доводить, що це працює**
- **Обробка фону, яка не блокує ваші додатки**
- **Витримувальне використання помилок з автоматичними повторами**

Якщо ви' використовуєте аналізи Умамі в .NET програмі(МSK2), я(M SK3) хочу, щоб ви спробували [Umami.NET](https://github.com/scottgal/mostlylucidweb/tree/main/Umami.Net). Це МSK1 відкритий вихідний код МSK2 серйозно тестований , і розроблений для того, щоб зробити ваше життя легшим

У мене є питання чи підказки? Відкрийте проблему на GitHub або зверніть увагу на її коментарі