SDK

SDK overview

Architecture, bundle size, transport layer, and entry points for @trackrift/sdk.

AI brief: Trackrift ships @trackrift/sdk: zero heavy deps, client batching to POST /collect, bootstrap GET /bootstrap for cookies, optional React/Next wrappers, server sendServerEvent to POST /s2s/collect. Universal script is /v1/u.js?id=PUBLIC_ID. Target bundle <8KB gzipped.

The @trackrift/sdk is a first-party tracking client designed for marketing sites, SaaS apps, and headless storefronts. It prioritizes small bundle size, resilient delivery (sendBeacon on unload), and event_id compatibility with Meta/Google pixels for deduplication.

Package exports

Export	Use when	Bundle impact
@trackrift/sdk	Vanilla JS, Vite, custom bundlers	Core ~6–8KB gz
@trackrift/sdk/react	React 18+ SPAs	Core + thin provider hooks
@trackrift/sdk/next	Next.js App Router	Adds page_view + autocapture wiring
@trackrift/sdk/server	Node / Edge server only	No browser code — tree-shake client bundle

Runtime architecture

The client maintains an in-memory event queue. Events flush when: (a) queue reaches batchSize, (b) batchIntervalMs elapses, (c) visibilitychange to hidden, or (d) beforeunload. Transport order: navigator.sendBeacon → fetch(..., { keepalive: true }).

lifecycle.ts

// Simplified lifecycle
tracker.init({ endpoint, publicId });
// → GET /bootstrap (cookies)
// → optional installAutocapture()
tracker.track('page_view');
// → enqueue → flush → POST /collect

Collector endpoints (browser)

Method	Path	Purpose
GET	/bootstrap	Issue _aid / _ses cookies; ?aid= for cross-domain handoff
POST	/collect	Batch ingest (max payload per OpenAPI spec)
POST	/m	Magic link identity merge (?_uid= signed token)
GET	/v1/u.js	Loader — injects init config from public_id

Recommended install

For most sites use the Universal Script from Settings → Tracking. It injects accountId/publicId automatically via /v1/u.js?id=YOUR_PUBLIC_ID and enables autocapture without a build step.

SSR / hybrid apps

The tracker is a browser singleton. Guard init with typeof window checks or use disabled:true during SSR. Next.js users should mount TrackerProviderNext in a client layout segment only.