SDK overview

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

All five SDKs do the same job — get events to the ingest API — but they split into three 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.
Turnkey. No code at all: install something in the platform you already run and it produces the right signals on its own. Today that is the WooCommerce plugin, which also imports your order history.

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
WooCommerce	WordPress stores — no code	queued, batched	`X-Api-Key`

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.