CDN & Infrastructure

How the SDK is distributed and how events reach the server: batched, unload safe and idempotent.

View as Markdown Open in Claude Open in ChatGPT

The SDK ships as the orwel npm package with a self-contained UMD build (~60 KB, dependencies bundled). Use it from a CDN with zero build step, or install it into any bundler-based app.

Distribution

<script src="https://cdn.jsdelivr.net/npm/orwel@1/dist/orwel.umd.js"></script>

The UMD bundle attaches the SDK to window.orwel; the ESM build is used by bundlers automatically. Both are served by any npm CDN (jsDelivr, unpkg).

The pipeline

mermaid

flowchart LR
  A[Orwel SDK<br/>browser] -->|batched events| B[Ingest API<br/>api.orwel.io]
  B --> C[(Supabase<br/>per-workspace)]
  C --> D[Intent signals<br/>Bayesian patterns]
  C --> E[Dashboard<br/>features and journeys]

How events reach the server

The SDK never blocks your app. Events are queued (in memory and localStorage, up to 1000) and flushed in batches to keep requests few and small.

Batched in chunks of 100

Events post to /ingest/batch with keepalive: true so in-flight requests survive navigation. Since SDK 1.7.1 the queue is split into chunks of 100 events, the most the server accepts in one batch, and the chunks are sent one after another.

Rejected events are logged, not retried

Failed events are dropped instead of requeued, so one bad event can never loop forever. Since 1.7.1 a rejection (HTTP 400) is logged in the console with the server response and the rejected codes. A batch accepted in part answers HTTP 207 and lists the refused events in failedEvents. See Troubleshooting.

Unload-safe

On beforeunload / tab hide, the queue is flushed via navigator.sendBeacon (falling back to a sync request) so the last events aren't lost.

Safe to retry

Each event carries a unique id and conversions carry a conversionId, so the server absorbs retries without doubling records, and the unload time sendBeacon flush never duplicates visitor activity.

Timestamped

Every event is stamped with an ISO timestamp at the moment it's queued; sessions track their own startedAt, updatedAt, and finishedAt. Useful for ordering, latency analysis, and reconstructing real-time journeys.

Ingest endpoints

Endpoint	Purpose
`POST /ingest`	Single event / session / conversion.
`POST /ingest/batch`	A batch of up to 100 events (the common path). Answers 200, 207 (partial) or 400 / 500.
`POST /visitor-resolve`	Resolve a stable visitor id from a fingerprint.

Every request is authenticated with the X-Orwel-Key header (your public or development key), which maps to a workspace. Events are always scoped to that workspace, so your data never mixes with another's. These keys can only write; reading uses API keys.