@clarity/tracker

Tiny (~1kb gzip), cookieless, SPA-aware analytics tracker. No cookies, no localStorage, no persistent IDs. Respects Do-Not-Track / Global Privacy Control. Pairs with the self-hosted clarity collector, but will POST to any endpoint that accepts its JSON.

Install

npm i @clarity/tracker

import clarity from "@clarity/tracker";

clarity.init({
  site: "myapp.com",
  endpoint: "https://analytics.example.com/api/event", // default "/api/event"
});

// custom events
clarity.track("Signup");
clarity.track("Trial Started", { props: { plan: "pro" } });

// revenue attribution
clarity.revenue(49, { name: "Purchase" });
// or
clarity.track("Purchase", { revenue: 49 });

Pageviews (including SPA route changes via history.pushState) are tracked automatically. Disable with autoPageviews: false.

Script tag (no build step)

<script defer
  data-site="myapp.com"
  data-endpoint="https://analytics.example.com/api/event"
  src="https://unpkg.com/@clarity/tracker/dist/clarity.js"></script>

Then anywhere: window.clarity.track("Purchase", { revenue: 49 }).

data-* attributes

| Attribute | Default | Meaning | | ---------------- | -------------- | ---------------------------------------- | | data-site | — | Required property id | | data-endpoint | /api/event | Collector URL | | data-auto | true | Auto pageviews; false to disable | | data-hash | false | Count hash changes as pageviews | | data-localhost | false | Send events from localhost too |

API

init(options: ClarityOptions): ClarityApi
track(name: string, opts?: { revenue?: number; props?: object; path?: string }): void
revenue(amount: number, opts?: { name?: string; props?: object }): void

What it sends

{
  "site": "myapp.com",
  "name": "pageview",          // or your event name
  "path": "/pricing",
  "referrer": "https://news.ycombinator.com/",
  "utm": { "source": "newsletter", "medium": "email" },
  "width": 1440,
  "ts": 1721563200000,
  "revenue": 49                // only on revenue events
}

No IP address, cookie, or fingerprint is sent. The collector derives an anonymous, daily-rotating visitor hash server-side and never stores raw IPs.

License

MIT