{"_id":"@aptxx/tracktag","_rev":"3-7d116349e0795c3b479232cf7dbd1ace","name":"@aptxx/tracktag","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.2":{"name":"@aptxx/tracktag","version":"0.0.2","license":"MIT","_id":"@aptxx/tracktag@0.0.2","maintainers":[{"name":"aptxx","email":"prestorpan@gmail.com"}],"homepage":"https://github.com/aptxx/tracktag","bugs":{"url":"https://github.com/aptxx/tracktag/issues"},"dist":{"shasum":"8048c331a46ed77c6243a3775f09c593f755e4af","tarball":"https://registry.npmjs.org/@aptxx/tracktag/-/tracktag-0.0.2.tgz","fileCount":7,"integrity":"sha512-fGq880VG1XVvtEyc9ty6gAaGrxLZOP1a3i08dG3B9V8K0tqwNAiB2zK1Fs/cq+WIHCyZen1K4ZghsE+KfmBgqA==","signatures":[{"sig":"MEYCIQCt2O69yIQ0PZpyvf+ko329aEip6AeRoW87go6P9S9SOgIhAKOHQr0WewSgk+j320FgmUwd8bN94iuLAdxHhpyUbMBX","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68216},"type":"module","gitHead":"630f1dd42f635454b474b242379cd2d01ef0c7bb","scripts":{"dev":"node scripts/build.mjs --watch","lint":"eslint .","test":"vitest run","build":"node scripts/build.mjs","example":"node examples/lander/mock-server.js","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"aptxx","email":"prestorpan@gmail.com"},"repository":{"url":"git+https://github.com/aptxx/tracktag.git","type":"git"},"_npmVersion":"10.8.2","description":"Lightweight client-side tracking SDK for Lander pages","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.0.0","vitest":"^1.6.0","esbuild":"^0.21.0","globals":"^17.7.0","@eslint/js":"^9.5.0","typescript":"^5.4.0","@types/node":"^26.0.1","typescript-eslint":"^7.13.0","@vitest/coverage-v8":"^1.6.0"},"_npmOperationalInternal":{"tmp":"tmp/tracktag_0.0.2_1784128965027_0.8927917982498994","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@aptxx/tracktag","version":"0.0.3","license":"MIT","_id":"@aptxx/tracktag@0.0.3","maintainers":[{"name":"aptxx","email":"prestorpan@gmail.com"}],"homepage":"https://github.com/aptxx/tracktag","bugs":{"url":"https://github.com/aptxx/tracktag/issues"},"dist":{"shasum":"00a2d96b886baba9cf08d22ba0ee1d16545239c9","tarball":"https://registry.npmjs.org/@aptxx/tracktag/-/tracktag-0.0.3.tgz","fileCount":7,"integrity":"sha512-1ch46Z2k8VP/K9JAzHz4GfVoi55Vb2yS8t8p2SYNWQBBRlcsvsDUqqKkTan7NmTThkL+/8j6DqrtdeWOLDaPeQ==","signatures":[{"sig":"MEQCIClrg4UsGOlCdE++vR/WBpljCHfTXl1acXtdxr8mXvR+AiBoAFkMzN+lnHIdUdNgfmxxyLMejbLDZa/FG7DVwR/SAg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68518},"type":"module","gitHead":"11c658bbd8bce1f662b4b8ba8b915c22703a8db0","scripts":{"dev":"node scripts/build.mjs --watch","lint":"eslint .","test":"vitest run","build":"node scripts/build.mjs","example":"node examples/lander/mock-server.js","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"aptxx","email":"prestorpan@gmail.com"},"repository":{"url":"git+https://github.com/aptxx/tracktag.git","type":"git"},"_npmVersion":"10.8.2","description":"Lightweight client-side tracking SDK for Lander pages","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.0.0","vitest":"^1.6.0","esbuild":"^0.21.0","globals":"^17.7.0","@eslint/js":"^9.5.0","typescript":"^5.4.0","@types/node":"^26.0.1","typescript-eslint":"^7.13.0","@vitest/coverage-v8":"^1.6.0"},"_npmOperationalInternal":{"tmp":"tmp/tracktag_0.0.3_1784133534047_0.5156809915312006","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@aptxx/tracktag","version":"0.0.4","description":"Lightweight client-side tracking SDK for Lander pages","license":"MIT","homepage":"https://github.com/aptxx/tracktag","repository":{"type":"git","url":"git+https://github.com/aptxx/tracktag.git"},"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"node scripts/build.mjs --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","lint":"eslint .","example":"node examples/lander/mock-server.js"},"devDependencies":{"@eslint/js":"^9.5.0","@types/node":"^26.0.1","@vitest/coverage-v8":"^1.6.0","esbuild":"^0.21.0","globals":"^17.7.0","jsdom":"^24.0.0","typescript":"^5.4.0","typescript-eslint":"^7.13.0","vitest":"^1.6.0"},"publishConfig":{"access":"public"},"_id":"@aptxx/tracktag@0.0.4","gitHead":"2b66a3663054bd890c2d4141988f17415bc7384b","bugs":{"url":"https://github.com/aptxx/tracktag/issues"},"_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-OMhjc1B9uTOKnoLPJcxxfQRcljEsfgtdtXUES2MV6pAKJMtlc+LWUpBwcj6fqYPbcRF+mSkCcPkeOSb2TKtf9g==","shasum":"2149c0c32e356dc8250f2bb130333a0e5ca9e4be","tarball":"https://registry.npmjs.org/@aptxx/tracktag/-/tracktag-0.0.4.tgz","fileCount":7,"unpackedSize":74193,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDd6/IWorcNgoK82yOf4J/LM6/8GtH6EORbm3vl89y6ZAIhAJKINe1bG7qg4TIYfy2fyQ1DkB2g5uyuqUFlI1cGeCcV"}]},"_npmUser":{"name":"aptxx","email":"prestorpan@gmail.com"},"directories":{},"maintainers":[{"name":"aptxx","email":"prestorpan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tracktag_0.0.4_1786452408058_0.5211038295633337"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-15T15:22:44.888Z","modified":"2026-08-11T12:46:48.370Z","0.0.2":"2026-07-15T15:22:45.181Z","0.0.3":"2026-07-15T16:38:54.194Z","0.0.4":"2026-08-11T12:46:48.217Z"},"bugs":{"url":"https://github.com/aptxx/tracktag/issues"},"license":"MIT","homepage":"https://github.com/aptxx/tracktag","repository":{"type":"git","url":"git+https://github.com/aptxx/tracktag.git"},"description":"Lightweight client-side tracking SDK for Lander pages","maintainers":[{"name":"aptxx","email":"prestorpan@gmail.com"}],"readme":"# tracktag\n\nLightweight client-side tracking SDK for Lander pages. Records clicks, fires\nthird-party click trackers, and reports conversions to a tracking server\n(Voluum / Binom style).\n\n- **Zero runtime dependencies.** Small footprint, no hard size budget.\n- **Server-authored URLs.** The SDK never synthesizes or signs URLs — every\n  `clickUrl` / `clickTrackers` / `postbackUrl` comes from the Click endpoint\n  response.\n- **Smart transport.** clickTrackers: `sendBeacon` → `Image` → `fetch`; conversion/update: `Image` pixel (CORS-safe).\n\n## Install\n\nVia CDN (jsDelivr):\n\n```html\n<!-- @latest always points to the newest release -->\n<script src=\"https://cdn.jsdelivr.net/npm/@aptxx/tracktag@latest/dist/tracktag.min.js\"></script>\n```\n\nFor production, pin a specific version so breaking changes don't auto-roll into your pages:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@aptxx/tracktag@0.0.2/dist/tracktag.min.js\"></script>\n```\n\nOr download `dist/tracktag.min.js` and host it yourself.\n\n## Usage\n\n```html\n<!-- Async-load the SDK -->\n<script async src=\"https://cdn.jsdelivr.net/npm/@aptxx/tracktag@latest/dist/tracktag.min.js\"></script>\n\n<!-- Publisher stub: buffers calls into .q before the SDK loads -->\n<script>\n  window.tracktag = window.tracktag || function () {\n    (window.tracktag.q = window.tracktag.q || []).push(arguments);\n  };\n</script>\n<script>\n  tracktag('config', { endpoint: 'https://track.example.com/click' });\n</script>\n\n<button onclick=\"tracktag('event', 'clickout')\">CTA</button>\n<button onclick=\"tracktag('event', 'conversion', { payout: '29.90', txid: 'order_998' })\">Confirm</button>\n```\n\nSend intermediate signals keyed by clickId:\n\n```html\n<button onclick=\"tracktag('event', 'update', { step: 'checkout' })\">Checkout</button>\n```\n\n`update` fires an `Image` pixel to `{endpoint}` with caller params. The SDK injects `clid`, `_event=update`, `_output=pixel`, `_cb` (non-overridable). Repeatable.\n\nThe 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.\n\nTracking 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.\n\n## clid-provided mode (`clid` in the URL)\n\nWhen a visitor arrives via a tracker redirect, the click id is already in the\npage URL as `?clid=...` (e.g. `https://lander.example.com/?clid=abc123`). The\nSDK detects it and **skips the `config` Click request** — no fetch, the `clid`\nis used directly. The same `config({ endpoint })` call and CTA wiring serve\nboth arrival types; publishers change nothing. Per-event behavior in this mode\nis noted in the [API table](#api) below.\n\n> Cross-domain note: the SDK reads `clid` only from the page URL — a cookie set\n> on the tracker's own domain isn't readable by the lander (same-origin). The\n> click id must arrive via the URL, or via a first-party tracker script on the\n> lander that re-exposes it.\n\n## API\n\n```ts\ndeclare function tracktag(command: 'config', opts: Options): void;\ndeclare function tracktag(command: 'event', name: string, params?: EventParams): void;\n\ninterface Options {\n  endpoint: string;\n  debug?: boolean;\n}\n\ninterface Click {\n  clickId: string;\n  clickUrl?: string;\n  clickTrackers?: string[];\n  postbackUrl?: string;\n}\n\ntype EventParams = Record<string, string | number | boolean>;\n```\n\nEvent names:\n\n| Name          | Behavior                                                                             |\n| ------------- | ----------------------------------------------------------------------------------- |\n| `'clickout'`  | Fire `clickTrackers` beacons (`sendBeacon` → `Image` → `fetch`), then navigate to `clickUrl`. No-op when absent/empty. |\n| `'conversion'`| Fire `Image` pixel to `postbackUrl` with caller params. Repeatable.     |\n| `'update'`    | Fire `Image` pixel to endpoint with caller params. Repeatable.         |\n\nIn clid-provided mode (`?clid=` in the URL) `clickout` instead navigates to `{endpoint}?clid={clid}` and `conversion`/`update` no-op — see [clid-provided mode](#clid-provided-mode-clid-in-the-url).\n\n## Development\n\n```bash\npnpm install\npnpm test              # Vitest + jsdom\npnpm run typecheck\npnpm run lint\npnpm run build         # IIFE, IIFE-min\npnpm run example       # local Lander fixture + mock server on :5173\n```\n\nSee `AGENTS.md` for the full design spec, invariants, and contribution rules.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}