SDK overview

How the ChurnWarn SDKs work, and which one to reach for.

All four SDKs do the same job — get events to the ingest API — but they split into two families.

Capture vs. direct send

Capture (recommended). Call an initialize / configure once, then fire captureEvent from anywhere. Events are buffered in memory and flushed in the background to POST /api/events/batch. Non-blocking, batched, resilient to short network blips. Available in .NET, Node, Python.
Direct send. A thin fetch to POST /api/events per event, awaited by you. Best in the browser SDK and for low-volume server scripts.

Rule of thumb

Use capture on the server (high volume, you control the process lifetime). Use the browser SDK's fire-and-forget send on the client. Reach for raw HTTP only where no SDK fits.

Choosing an SDK

SDK	Best for	Transport	Auth
Browser JavaScript	SPAs, marketing sites	`POST /api/events`	Bearer
Node.js	Node services, APIs	batched	`X-Api-Key` or Bearer
Python	Django/Flask/FastAPI, workers	batched	`X-Api-Key` or Bearer
.NET	ASP.NET, background services	batched	`X-Api-Key` or Bearer

Shared concepts

Every SDK speaks the same data model:

externalAccountId — the account id in your system (max 100 chars). This is how ChurnWarn groups events into an account-level score.
eventType — a canonical metric (feature_used), a dotted raw name (app.login), or any custom string you map in Settings → Event map.
payload — a small JSON object of context. Sent on the wire as a JSON string.
Batching — server SDKs cap each HTTP request at 500 events; larger buffers are split automatically.
Redaction — payload masking is on by default in every SDK. See Security & data masking.

Canonical metrics

The SDKs ship a Metrics constant mirroring the backend's default dashboard keys, so you avoid typos:

login · active_user · feature_used · session · onboarding_completed · plan_upgraded · seat_purchased · seat_used · seat_expanded · referral · nps_response · csat_response · support_ticket_opened · support_ticket_resolved · support_ticket_negative

You can send any string you like — unmapped types are stored raw and can be routed to a metric later from the event map.