Quick start

This page gets a pageview from your site into the leatmap collector at collect.leatmap.com in under five minutes. It assumes you already have a leatmap workspace and an API key. If you do not, sign up at app.leatmap.com and grab a key from Settings → API keys.

1. Install the SDK

npm install @syntarie/tracking
# or
pnpm add @syntarie/tracking
# or
yarn add @syntarie/tracking

The package is ESM-only and has zero runtime dependencies.

2. Initialise once on page load

Place this as early in your bootstrap as you can — Leatsmap does no blocking work, but the earlier init runs the more accurate the first pageview’s referrer attribution will be.

import { init } from '@syntarie/tracking';

init({
  siteId: 'site_marketing',
  host: 'https://collect.example.com',
});

That single call:

1. Records the current page as a pageview event.
2. Listens for pushState / replaceState / popstate and emits a new pageview on every SPA navigation.
3. Mints (or re-uses) an anonymous device id, persisted via cookie + a localStorage fallback.
4. Honours navigator.doNotTrack === '1' by default — DNT-blocked init never installs listeners and every subsequent send is a no-op.

3. Send a custom event

import { track } from '@syntarie/tracking';

track('checkout_completed', {
  order_id: 'ord_42',
  total_cents: 4900,
  currency: 'USD',
});

track() calls before init are dropped silently — there is no global queue that fills up before bootstrap.

4. Identify the user (optional)

import { identify } from '@syntarie/tracking';

identify('user_42', { plan: 'pro' });

Calling identify() for the first time binds the current anonymous id to the known user id. If a different user id was previously bound, Leatsmap emits a merge event before the new identify so cross-device timelines stay consistent.

5. Verify in the query API

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://localhost:8081/sites/site_marketing/pageviews?from=2026-05-01&to=2026-05-02"

Response:

{
  "count": 1,
  "by_day": [{ "date": "2026-05-02", "count": 1 }]
}

You now have a working pipeline. From here:

• Add the Web Vitals module for performance.
• Define a tracking plan and turn on validation at the collector.
• Read the Privacy & compliance section before going to production.