tracktag

Lightweight client-side tracking SDK for Lander pages. Records clicks, fires third-party click trackers, and reports conversions to a tracking server (Voluum / Binom style).

• Zero runtime dependencies. Small footprint, no hard size budget.
• Server-authored URLs. The SDK never synthesizes or signs URLs — every clickUrl / clickTrackers / postbackUrl comes from the Click endpoint response.
• Smart transport. clickTrackers: sendBeacon → Image → fetch; conversion/update: Image pixel (CORS-safe).

Install

Via CDN (jsDelivr):

<!-- @latest always points to the newest release -->
<script src="https://cdn.jsdelivr.net/npm/@aptxx/tracktag@latest/dist/tracktag.min.js"></script>

For production, pin a specific version so breaking changes don't auto-roll into your pages:

<script src="https://cdn.jsdelivr.net/npm/@aptxx/[email protected]/dist/tracktag.min.js"></script>

Or download dist/tracktag.min.js and host it yourself.

Usage

<!-- Async-load the SDK -->
<script async src="https://cdn.jsdelivr.net/npm/@aptxx/tracktag@latest/dist/tracktag.min.js"></script>

<!-- Publisher stub: buffers calls into .q before the SDK loads -->
<script>
  window.tracktag = window.tracktag || function () {
    (window.tracktag.q = window.tracktag.q || []).push(arguments);
  };
</script>
<script>
  tracktag('config', { endpoint: 'https://track.example.com/click' });
</script>

<button onclick="tracktag('event', 'clickout')">CTA</button>
<button onclick="tracktag('event', 'conversion', { payout: '29.90', txid: 'order_998' })">Confirm</button>

Send intermediate signals keyed by clickId:

<button onclick="tracktag('event', 'update', { step: 'checkout' })">Checkout</button>

update fires an Image pixel to {endpoint} with caller params. The SDK injects clid, _event=update, _output=pixel, _cb (non-overridable). Repeatable.

The function stub buffers every tracktag(...) call into .q. Once the SDK loads, it drains .q serially behind the first config, then replaces the stub with the real function — so later tracktag(...) calls enqueue and run immediately.

Tracking is best-effort: a failed Click fetch, any event before config resolves, or a malformed response is silently skipped — it never throws to the page. Pass debug: true on config to log activity and failures to the console.

clid-provided mode (clid in the URL)

When a visitor arrives via a tracker redirect, the click id is already in the page URL as ?clid=... (e.g. https://lander.example.com/?clid=abc123). The SDK detects it and skips the config Click request — no fetch, the clid is used directly. The same config({ endpoint }) call and CTA wiring serve both arrival types; publishers change nothing. Per-event behavior in this mode is noted in the API table below.

Cross-domain note: the SDK reads clid only from the page URL — a cookie set on the tracker's own domain isn't readable by the lander (same-origin). The click id must arrive via the URL, or via a first-party tracker script on the lander that re-exposes it.

API

declare function tracktag(command: 'config', opts: Options): void;
declare function tracktag(command: 'event', name: string, params?: EventParams): void;

interface Options {
  endpoint: string;
  debug?: boolean;
}

interface Click {
  clickId: string;
  clickUrl?: string;
  clickTrackers?: string[];
  postbackUrl?: string;
}

type EventParams = Record<string, string | number | boolean>;

Event names:

| Name | Behavior | | ------------- | ----------------------------------------------------------------------------------- | | 'clickout' | Fire clickTrackers beacons (sendBeacon → Image → fetch), then navigate to clickUrl. No-op when absent/empty. | | 'conversion'| Fire Image pixel to postbackUrl with caller params. Repeatable. | | 'update' | Fire Image pixel to endpoint with caller params. Repeatable. |

In clid-provided mode (?clid= in the URL) clickout instead navigates to {endpoint}?clid={clid} and conversion/update no-op — see clid-provided mode.

Development

pnpm install
pnpm test              # Vitest + jsdom
pnpm run typecheck
pnpm run lint
pnpm run build         # IIFE, IIFE-min
pnpm run example       # local Lander fixture + mock server on :5173

See AGENTS.md for the full design spec, invariants, and contribution rules.

License

MIT