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). It also carries the one call that reports what a reader did with an article: see Content interactions.

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)
});

Content interactions

One call reports what a reader did with an article, from the page that just rendered it:

engage.reportInteraction({
  action: "content.read",                        // or content.shared, content.liked
  id: article.id,                                // the article's id from the content API
  userId: viewer.platformUserId                  // the reader's platform user id
});

That posts to POST /v1/content-interactions with the same publishable ek_live_… key the client already holds, so a page that already loads the SDK adds one line. The article ids come from the content API, and Render a club’s articles has it in place on a working page. It takes no tags, and there is no option to add any: the server reads the article’s tags off the article. If a caller could send them, your developers and your marketers would be choosing tag strings for the same vocabulary, and members’ tag affinity would split in two. Leave userId out and the client identity is used instead, when that identity is a platform user id (identify({ userId })). A member external id does not work here, because this endpoint resolves readers by platform user id only. Only signed-in readers can be reported, so an anonymous reader is invisible to these counts rather than counted anonymously. Passing userId blank says exactly that, which is why a blank one drops instead of falling back to the identity: an empty string is what a template renders once the reader signs out, and the read is not theirs.

Condition	Behaviour
No `userId` and no user id identity	Dropped without a request (nobody is signed in); surfaced via `onError`
Blank `userId`	Dropped without a request, identity or not; surfaced via `onError`
Blank content id, unknown action or type	Dropped without a request; surfaced via `onError`
Same report already in flight	Dropped as a duplicate, silently — a render loop cannot multiply one read
Page already hidden	Sent with `navigator.sendBeacon`, so a read reported as the reader leaves still lands
Otherwise	`keepalive` fetch. If it fails while the page is hidden, one beacon attempt takes over and its delivery is unknown; any other failure is surfaced via `onError` as code `network_error`
Server refusal	Surfaced via `onError` as code `rejected_events`; not retried

Reports are not batched or queued: the endpoint takes one per request. A read counts once per member, per article, per day, so a refresh does not inflate the number and a redelivered report is deduped rather than double-counted. A refusal arrives as a 202 naming a reason, not as an error, because each one is a normal state of a page rather than a broken request:

Reason	What it means
`anonymous_reader`	No reader id reached the server
`unknown_member`	That platform user id is not an active member of your club
`unknown_content`	No published article of that id here (a draft answers the same way)
`content_untagged`	The article carries no tag, so there is no affinity to raise

content_untagged is the one worth wiring an alert for: an article published with no tags reports zero reads forever, and tagging it fixes reads from that point on.

Content interactions never earn XP, and no setting changes that. A read reported by a browser cannot be trusted to pay out. See the content API overview.

Flushing

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

Both also wait for interaction reports still in the air.

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

Content API

SDK

Quick start

Identity

Delivery semantics

Content interactions

Flushing

Config reference

Tags

​Quick start

​Identity

​Delivery semantics

​Content interactions

​Flushing

​Config reference

​Tags

Quick start

Identity

Delivery semantics

Content interactions

Flushing

Config reference

Tags