.NET SDK

EnmaClient

Основная точка входа. Клиент реализует IAsyncDisposable, поэтому рекомендуется использовать await using:

await using var enma = new EnmaClient(o =>
{
    o.ApiToken       = "sdk_your_token";
    o.OrganizationId = Guid.Parse("...");
    o.ProjectId      = Guid.Parse("...");
    o.SdkClientId    = Guid.Parse("...");
});

При завершении (DisposeAsync) все оставшиеся события автоматически отправляются на сервер.

Track(eventName, configure?)

Fire-and-forget отправка. Событие помещается в очередь и отправляется в фоне. Возвращает управление немедленно.

// Минимальный вызов
enma.Track("page.viewed");

// С данными
enma.Track("order.created", e =>
{
    e.Actor.UserId = "user-42";
    e.Payload = new { Amount = 99.99, Currency = "USD" };
    e.Tag("region", "eu-west");
});

TrackAsync(eventName, configure?, ct?)

Асинхронная отправка. Task завершается, когда событие доставлено на сервер. Используйте, когда нужна гарантия доставки.

await enma.TrackAsync("payment.processed", e =>
{
    e.Actor.UserId = "user-42";
    e.Payload = new { TransactionId = "tx-001", Amount = 150.00 };
    e.Tag("provider", "stripe");
});

FlushAsync(ct?)

Принудительная отправка всех буферизованных событий. Полезно перед завершением приложения, если не используется await using или ASP.NET Core интеграция.

await enma.FlushAsync();

EventBuilder

Callback-построитель настраивает отдельные события:

Ключи процессов

Привязывайте события к экземплярам процессов. Одно событие может быть связано с несколькими процессами:

enma.Track("step.completed", e =>
{
    e.Actor.UserId = "user-42";
    e.ProcessKey(Guid.Parse("...process-def-id..."), "order-123");
    e.ProcessKey("another-def-id-guid", "session-456");
});

Теги

Теги — это метаданные ключ-значение. Теги события имеют приоритет над DefaultTags при совпадении ключей:

enma.Track("item.added", e =>
{
    e.Tag("category", "electronics");
    e.Tags(new Dictionary<string, string>
    {
        ["source"] = "mobile",
        ["ab_test"] = "variant-b"
    });
});

Middleware

Используйте middleware для обогащения или фильтрации событий перед помещением в очередь. Вызовите next, чтобы передать событие дальше по конвейеру, или пропустите вызов, чтобы отбросить событие:

var enma = new EnmaClient(o =>
{
    // ... учётные данные

    // Добавляем имя хоста к каждому событию
    o.Use(next => async (evt, ct) =>
    {
        evt.Tags ??= new Dictionary<string, string>();
        evt.Tags["host"] = Environment.MachineName;
        await next(evt, ct);
    });

    // Фильтруем внутренние события
    o.Use(next => async (evt, ct) =>
    {
        if (!evt.EventName.StartsWith("internal."))
            await next(evt, ct);
    });
});

Middleware выполняется в порядке регистрации.

Обработка ошибок

Зарегистрируйте callback для обработки ошибок доставки:

var enma = new EnmaClient(o =>
{
    // ... учётные данные

    o.OnError = (events, ex) =>
    {
        Console.Error.WriteLine(
            $"Не удалось отправить {events.Count} событий: {ex.Message}");
    };
});