SDK

tracker API

init, track, identify, consent, link, flush, reset, and event_id deduplication.

AI brief: Singleton tracker: init({endpoint, publicId, consentMode, batchSize}). track(name, payload) returns event_id. identify({email,user_id,traits}). setConsent(). link(url) adds ?_aid. getEventId(name) for pixel dedupe. reset() clears queue and session.

tracker is a singleton exported from @trackrift/sdk. Call init() exactly once per page lifecycle before any track(). Subsequent init() calls merge options but do not reset identity.

events.ts

import { tracker } from '@trackrift/sdk';

tracker.init({
  endpoint: 'https://api.trackrift.com',
  publicId: 'YOUR_PUBLIC_ID',
  batchSize: 10,
  batchIntervalMs: 2000,
  consentMode: 'internal',
});

const eventId = tracker.track('purchase', {
  value: 297,
  currency: 'USD',
  content_ids: ['sku_starter'],
  properties: { plan: 'starter', coupon: 'MAY26' },
});

tracker.identify({
  email: '[email protected]',
  user_id: 'usr_42',
  traits: { first_name: 'Alice', company: 'Acme', mrr: 297 },
});

const checkoutUrl = tracker.link('https://checkout.example.com/cart');

Method reference

Method	Returns	Notes
init(options)	void	Required before track(); sync bootstrap
track(name, payload?)	event_id string	Dedupes 1500ms window without explicit event_id
identify({ email, user_id, traits })	void	Fires identify event + merges identity server-side
setConsent(ConsentState)	void	Required mode only — flushes queued events
link(url)	string	Appends ?_aid= for cross-domain
getEventId(name)	string \| undefined	Last event_id for name — pixel helper
reset()	void	Clears queue + anonymous session (logout flows)
flush()	Promise<void>	Force send queue now

TrackerInitOptions

Field	Default	Notes
endpoint	required	Collector base URL, e.g. {{ENDPOINT}}
publicId	—	Workspace public id (12 chars)
accountId	—	Injected automatically by /v1/u.js
consentMode	internal	internal = always send; required = queue until setConsent
batchSize	10	Force flush when queue reaches this size
batchIntervalMs	2000	Scheduled flush window
debug	false	console.log [tracker] messages
disabled	false	No-op for tests / SSR guards

Edge cases

Double init in StrictMode: dedupe prevents duplicate page_view within 1500ms.
track() before init(): events are dropped with a debug warning — always init first.
Offline queue: events are not persisted to localStorage — lost on hard close if flush fails.
Custom event_id: pass in payload to reuse across pixel + SDK for dedupe.

explicit-event-id.ts

const sharedId = crypto.randomUUID();

tracker.track('purchase', { event_id: sharedId, value: 99, currency: 'USD' });
fbq('track', 'Purchase', { value: 99, currency: 'USD' }, { eventID: sharedId });

Dedupe window

Without an explicit event_id, identical event_name + pathname within 1500ms is ignored (StrictMode / double-click protection).