tracker

Tracker SDK is a minimal‑size web analytics library designed for quick integration into modern web applications, especially those generated by AI‑assisted tools like Vibe Coding. It focuses on simplicity: a single `init` call configures the collector endpoint, after which pageviews are recorded automatically and custom events can be sent with `track(eventName, data)`. **Key capabilities** - **Zero‑configuration start** – Adding one script tag or an npm import is enough to begin collecting data. - **Automatic pageview detection** – The SDK listens to navigation events and sends a `pageview` payload without extra code. - **Custom event tracking** – Developers can log any interaction by calling `track` with a name and optional payload. - **Device fingerprinting** – A canvas‑based fingerprint uniquely identifies visitors while respecting privacy. - **Offline queue** – Events that fail to send are stored in local storage and retried later, ensuring data loss is minimized. - **Session management** – Sessions are created automatically and expire after a configurable timeout (default 30 minutes). - **Configurable batching** – Events are grouped into a single request to reduce network overhead. **Installation** - **CDN** – Include the UMD bundle directly in HTML and call `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** – `npm install @weavefox/tracker` then import the functions: `import { init, track, setUserId } from '@weavefox/tracker';`. **Public API** | Method | Purpose | |--------|---------| | `init(config)` | Initialise the SDK with endpoint, appId, and optional flags. | | `track(eventName, data)` | Send a custom event. | | `trackPageview(data)` | Manually record a page view (auto‑enabled by default). | | `setUserId(userId)` | Associate a logged‑in user with subsequent events. | | `getFingerprint()` | Retrieve the generated device fingerprint. | | `flush()` | Immediately dispatch any queued events. | **Configuration options** ```javascript WFTK.init({ endpoint: 'required', // URL of the collector service appId: 'optional', // Identifier for the application autoPageview: true, // Auto‑track page views debug: false, // Enable console debugging enableQueue: true, // Store events offline when network fails sessionTimeout: 1800000, // Session idle timeout in ms (default 30 min) maxEventsPerSession: 1000 // Upper bound for events per session }); ``` **Payload format** – Each request contains a JSON body with an optional `appId` and an `events` array. Every event includes a mandatory `event` name, `timestamp`, `nonce` (for deduplication), `fingerprint`, and a `data` object with system‑collected context (URL, title, device info, etc.). User‑defined fields belong in the `biz` sub‑object, keeping analytics and business data separate. **Server‑side considerations** - **Timestamp validation** – Reject events older than 5 minutes to prevent replay attacks. - **Nonce deduplication** – Store nonces (e.g., in Redis) with a 24‑hour TTL to ensure idempotency. - **Rate limiting** – Apply per‑IP and per‑fingerprint limits to curb abuse. - **App identification** – Prefer an explicit `appId` in the payload; fallback to the request `Referer` host if needed. - **Example Express handler** – The README provides a concise Node.js snippet that validates timestamps, checks nonces, and persists events. **License** – Distributed under the MIT license, allowing unrestricted use in both open‑source and commercial projects. Overall, Tracker SDK offers a straightforward, privacy‑aware solution for developers who need reliable client‑side analytics without the overhead of heavyweight platforms.