Engagement SDK

The engagement SDK is a zero-dependency TypeScript client for POST /v1/track. It runs in browsers (with sendBeacon drain on page hide) and in Node 18+ (global fetch).

The SDK is not yet published to npm - your 4D contact provides the package during integration onboarding. Everything it does rides on the public /v1/track endpoint, so you can always start with plain HTTP and adopt the SDK later without changing anything server-side.

Quick start

import { createEngagementClient } from "engagement-sdk";

const engage = createEngagementClient({
  key: "ek_live_…",                             // publishable tracking key (not a secret)
  endpoint: "https://api.develop.fourdos.dev"   // events POST to <endpoint>/v1/track
});

// Who is engaging - the id YOUR system knows the user by (member external id):
engage.identify("cust-123");

// Fire tagged engagement events:
engage.track(["world_cup_26", "england", "kane"]);
engage.track(["world_cup_26", "highlights"], {
  action: "content_view",
  metadata: { content_id: "article-99" }
});

Events are batched (up to 20 per request, the server cap), auto-flushed every 2s while anything is queued, and drained via navigator.sendBeacon when the page is hidden or unloading. Every event carries a client-generated UUID event_id which the server dedupes on, so retries after network failures can never double-count tag affinity.

Identity

The platform only records engagement for known members. Identity comes from one of:

engage.identify("cust-123");                       // member external id (shorthand)
engage.identify({ memberExternalId: "cust-123" }); // same, explicit
engage.identify({ userId: "8a0f…uuid" });          // platform user id

engage.track(["kane"], { memberExternalId: "cust-456" }); // per-event override

Events tracked with no identity available are dropped and reported through onError - call identify() as soon as you know who the user is.

Delivery semantics

Condition	Behaviour
Network error / HTTP 429 / 5xx	Batch re-queued; retried on next flush (up to `maxAttempts`, default 3)
HTTP 401/403/422	Batch dropped (configuration error - retrying cannot succeed); surfaced via `onError`
Per-event `rejected` outcome (e.g. `unknown_member`)	Surfaced via `onError`; not retried
Per-event `duplicate` outcome	Treated as success (the event already landed)
Queue overflow (default 200)	Oldest events dropped; surfaced via `onError`

track() never throws. The only error surface is the onError callback:

const engage = createEngagementClient({
  key, endpoint,
  onError: (e) => console.warn("[engagement]", e.code, e.message)
});

Flushing

await engage.flush();     // send everything queued now
await engage.shutdown();  // final flush + detach timers/listeners (SPA teardown)

Config reference

Option	Default	Notes
`key`	-	Publishable `ek_live_…` tracking key
`endpoint`	-	API base URL
`identity`	-	Initial identity (else call `identify()`)
`flushIntervalMs`	`2000`	`0` disables timed flushing
`maxBatchSize`	`20`	Clamped to the server cap (20)
`maxQueueSize`	`200`	Oldest dropped beyond this
`maxAttempts`	`3`	Send attempts per event
`fetch`	`globalThis.fetch`	Injectable for tests/custom transports
`onError`	no-op	Drop/transport/rejection reporting
`autoFlushOnHide`	auto	Browser pagehide/visibility beacon drain

Get started

Concepts

Walkthroughs

SDK

Quick start

Identity

Delivery semantics

Flushing

Config reference

Tags

​Quick start

​Identity

​Delivery semantics

​Flushing

​Config reference

​Tags

Quick start

Identity

Delivery semantics

Flushing

Config reference

Tags