Install on your site

You’ve signed up at app.leatmap.com and created your workspace. This page gets the first event from your site into the dashboard.

1. Grab your workspace id

Open the Settings page on your dashboard. The Workspace ID field is at the bottom of the workspace card with a copy-to-clipboard button. It looks like:

11111111-1111-4111-8111-111111111111

Keep that handy — you’ll paste it into the SDK in step 3.

2. Install the SDK

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

The package is ESM-only with zero runtime dependencies. Modern bundlers (Vite, esbuild, Webpack 5, Next.js, Remix, Astro) resolve it without any extra configuration.

3. Initialize on page load

Add this as early as possible in your app bootstrap. The earlier init runs, the more accurate the first pageview’s referrer attribution.

Plain HTML

<script type="module">
  import { init } from 'https://esm.sh/@syntarie/tracking';
  init({
    siteId: 'YOUR_WORKSPACE_ID',
    host: 'https://c.leatmap.com',
  });
</script>

React / Next.js / Vite

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

init({
  siteId: 'YOUR_WORKSPACE_ID',
  host: 'https://c.leatmap.com',
});

Import that file once in your app root (e.g. app/layout.tsx for Next.js App Router, src/main.tsx for Vite).

import './leatmap';

That single init() call:

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

4. (Optional) Track custom events

pageview events are recorded automatically. Use track() for the moments that matter to your business:

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

track('signup_completed', {
  plan: 'pro',
  source: 'organic',
});

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

Calls to track() before init are silently dropped — there is no queue to overflow. If you call track() from a click handler that fires before your bootstrap has run, gate it with if (initialized) or move the bootstrap earlier.

5. Identify your users (optional, recommended)

When the user logs in, bind the anonymous device id to a stable user id so you can connect their pre-login and post-login activity:

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

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

This emits an identify event. If a different user id was previously bound on the same device, leatmap emits a merge event first so cross-session timelines stay consistent.

6. Verify it’s working

Open your site, navigate around for 10 seconds, then refresh the Overview page in your dashboard. You should see:

The “Events” KPI count tick up to at least 1.
The “Sessions” KPI count tick up to 1.
A small spike in the time-series chart.

If nothing appears within 1–2 minutes:

Open your browser DevTools → Network tab and look for a request to c.leatmap.com. The request should be a POST with status 202.
Check that siteId matches the workspace id from step 1.
Ensure init() runs on page load — console.log('leatmap init') right after the call confirms it executed.
Check that DNT (navigator.doNotTrack) is '0' or unset — the SDK is silent under DNT by design.

What’s next

Browser SDK reference — every public function with type signatures and edge-case notes.
Modules — Web Vitals, error capture, click delegation, scroll depth, etc.
Privacy & consent — DNT, IP anonymisation, per-event redaction.
TypeScript codegen — type-checked event names and payloads from your tracking plan.