Server SDK

💼 Business Context

• Server-side tracking is more trustworthy than client-side — it can't be blocked by an ad blocker or browser privacy setting
• Used for any event that originates or is confirmed server-side: payments, fulfillment, IoT telemetry, kiosk sessions
• Owned by Backend / Platform Engineering, used by every team building a server-side integration

🔌 Technical Overview

The .NET Server SDK is literally the Cxos.Ingestion.Client NuGet package itself — no separate wrapper needed. Non-.NET languages (Node.js, Python, Java) get thin clients generated from the same OpenAPI contract via an internal codegen pipeline, keeping every language binding schema-identical. Server SDK calls skip client-side consent gating (assumed already applied by the calling service) but still carry a required consent_basis field in the contract.

💾 Server SDK Call (.NET Core)

services.AddCxosIngestionClient(options =>
{
    options.Endpoint = "https://ingest.cxos.example.com";
    options.ApiKey = configuration["Cxos:ApiKey"];
});

await _cxosClient.TrackAsync(new CxosEvent
{
    Event = "payment_processed",
    UserId = "cust_004821",
    Properties = new { orderId = "ord_55123", amount = 3499 }
});

🔗 Integration Points

• Cxos.Ingestion.Client NuGet package (native .NET binding)
• Generated Node.js / Python / Java clients from the shared OpenAPI contract
• Azure API Management — server-to-server auth via API key or Azure AD managed identity
• Application Insights — the SDK propagates the caller's trace context automatically, so a server-emitted event is traceable end-to-end alongside client-emitted ones
• Used directly by every other connector/gateway described elsewhere in this handbook (IoT, Kiosk, batch connectors)

🧰 Services Consumed

• Owning microservice — Cxos.Ingestion.Api (see the Full Application Service Map)
• Database — Azure Cache for Redis (cache only)

⚠️ Non-Functional Considerations

• Scale: server-side callers can emit at much higher throughput than client SDKs — the Ingestion API applies per-caller rate limits
• Latency: typically sub-100ms for a synchronous call to Azure API Management within the same Azure region
• Reliability: built-in Polly retry policy with circuit breaker to avoid cascading failure if the Ingestion API is degraded
• Security/Privacy: server callers authenticate via Azure AD managed identity where possible, avoiding long-lived API keys

🎯 Enterprise Example

The payment service calls the Server SDK synchronously the moment a payment is confirmed, guaranteeing the payment_processed event lands before the order confirmation page renders — a stronger reliability guarantee than waiting for a client-side event that might never fire if the user closes the tab.