Braze.Api 3.0.0

.NET client library for the Braze Rest Api

This nuget package provides strongly typed API clients for Braze's API.

NOTE: unofficial and not affiliated with Braze in any way.

Usage

Configuration (e.g. appsettings.json):

{
  "Braze": {
    "BaseAddress": "https://rest.fra-02.braze.eu",
    "ApiKey": "<SECRET KEY>"
  }
}

service.AddBrazeApi();
// or as keyed services
// service.AddBrazeApi("KEY-A", "Braze:A");
// service.AddBrazeApi("KEY-B", "Braze:B");

Client usage:

var userDataClient = provider.GetRequiredService<IUserDataClient>();

// or via IBrazeProviderFactory (usful for keyed services)
// var factory = provider.GetRequiredService<IBrazeProviderFactory>();
// var brazeProvider = factory.Get("KEY-A");
// var userDataClient = brazeProvider.UserDataClient;

// or directly via keyed services
// var userDataClient = provider.GetRequiredKeyedService<IUserDataClient>("KEY-A");

var track = new Track()
{
    Attributes =
    [
        new()
        {
            BrazeId = "72BBAA5C-B137-4895-8735-B163A34CD133",
            Country = "NO",
            DateOfBirth = new DateOnly(2000, 12, 10),
            DateOfFirstSession = DateTimeOffset.Parse("2001-01-01T00:00:00Z"),
            Gender = Gender.PreferNotToSay,
            CustomAttributes = new ()
            {
                { "yolo", PropertyOp.Literal(42) },
                { "yolo_implicit", 42 },
                { "yolo2", PropertyOp.Literal(42.42) },
                { "yolo3", new PropertyOp.IncrementInteger() { IncrementValue = 42, } },
                { "yolo5", (string?)null },

            },
        }
    ],
    Events =
    [
        new ()
        {
            Name = "navn",
            Time = DateTimeOffset.Parse("2003-01-01T00:00:00+00:00"),
            Email = "yolo@foobar.com",
            Properties = new ()
            {
                { "thihi", Property.Create(DateTimeOffset.Parse("2004-01-01T00:00:00+00:00")) },
                { "foobar", 24.2 },
            },
        },
    ],
    Purchases =
    [
        new()
        {
            ProductId = "123",
            Currency = "NOK",
            Price = 42.42M,
            Time = DateTimeOffset.Parse("2002-01-01T00:00:00+00:00"),
            Properties = new ()
            {
                { "foobar", Property.Create("FOOBAR") }
            },
        },
    ]
};

await userDataClient.Track(track, CancellationToken.None);

Ecommerce Events (Beta)

⚠️ Beta: Ecommerce event support is currently in beta. Only OrderPlacedEvent has been tested end-to-end against the Braze API. Other events are implemented according to the Braze ecommerce events specification but may contain issues.

The following recommended ecommerce events are supported via strongly typed classes in the Braze.Api.UserData.ECommerce namespace:

Usage example:

var track = new Track()
{
    Events =
    [
        new OrderPlacedEvent()
        {
            ExternalId = "user-123",
            Time = DateTimeOffset.UtcNow,
            Properties = new OrderPlacedProperties
            {
                OrderId = "order-456",
                TotalValue = 99.99m,
                Currency = "USD",
                Source = "storefront",
                Products =
                [
                    new Product
                    {
                        ProductId = "prod-789",
                        ProductName = "T-Shirt",
                        VariantId = "tshirt_medium_blue",
                        Quantity = 1,
                        Price = 99.99m,
                    }
                ],
            },
        }
    ],
};

await userDataClient.Track(track, CancellationToken.None);

Development

The clients implemented in this package tries to replicate the logical structure in the Braze API documentation.

Testing

The project includes comprehensive test coverage:

• Unit Tests (Braze.Api.Tests): Serialization and model validation tests
• Integration Tests (Braze.Api.IntegrationTests): End-to-end tests that validate:
  • HTTP request formatting (method, URI, headers, body)
  • Response parsing and error handling
  • All documented error scenarios (401, 403, 404, 400, 429, 5XX)
  • Rate limiting header capture
  • Dependency injection configuration
  • JSON serialization compliance with Braze API spec

Run tests with:

dotnet test