Skip to content

Install on your site

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

1. Grab your API key and site id

Section titled “1. Grab your API key and site id”

Open the Install screen for your site on your dashboard (Settings, then your website, then Install). It shows two values you paste into the SDK in step 3:

  • API key. Your ingest key. It starts with lk_ and is shown only once when you create it, so copy it then. This authenticates your events.

    lk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  • Site id. A long id made of letters, numbers, and dashes. For a new workspace it is the same as your workspace id. The SDK sends it so the collector knows which site the events belong to.

    11111111-1111-4111-8111-111111111111

Keep both handy. The collector needs the key AND the site id; an event missing either one is rejected.

2. Install the SDK

Section titled “2. Install the SDK”
Terminal window
npm install @leadmaps/tracking
# or
pnpm add @leadmaps/tracking
# or
yarn add @leadmaps/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

Section titled “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.

The quickest safe path is the generated snippet on your site’s Install screen. Choose Consent mode, then open Settings > Cookie banners to design the managed banner. Save the design and copy the refreshed npm or CDN snippet. Its validated settings are embedded in the code, so no leadmaps settings request runs before consent.

Already using a consent platform? Select My existing consent platform and the generated snippet keeps the callback integration instead of rendering a second banner.

Plain HTML

Section titled “Plain HTML”
<script type="module">
  import { init, grantConsent } from 'https://esm.sh/@leadmaps/tracking';
  init({
    apiKey: 'YOUR_API_KEY',
    host: 'https://collect.leadmaps.nl',
    siteId: 'YOUR_SITE_ID',
    mode: 'cookied',
    autoCapture: 'heatmap',
  });
  // Replace this with your consent platform's real accept callback.
  yourConsentBanner.onAccept((record) => grantConsent(record.id));
</script>

React / Next.js / Vite

Section titled “React / Next.js / Vite”
src/leadmaps.ts
import { init, grantConsent } from '@leadmaps/tracking';


init({
  apiKey: 'YOUR_API_KEY',
  host: 'https://collect.leadmaps.nl',
  siteId: 'YOUR_SITE_ID',
  mode: 'cookied',
  autoCapture: 'heatmap',
});
// Replace this with your consent platform's real accept callback.
yourConsentBanner.onAccept((record) => grantConsent(record.id));

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

import './leadmaps';

That single init() 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. Creates a stable first-party browser id only after consent, so return visits from that browser stay connected. It does not claim that one browser always equals one person.
  4. 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

Section titled “4. (Optional) Track custom events”

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

import { track } from '@leadmaps/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.

Section titled “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 '@leadmaps/tracking';


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

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

6. Verify it’s working

Section titled “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.
  • Reopening the site in the same consented browser does not add another Unique visitor.
  • The active visitor count returns to 0 shortly after the last visible tab is closed. Older SDKs use a short recent-activity fallback.
  • A small spike in the time-series chart.

If nothing appears within 1–2 minutes:

  1. Open your browser DevTools, Network tab, and look for a request to collect.leadmaps.nl. The request should be a POST with status 202.
  2. Check that apiKey and siteId are both set and match the values from step 1. A request with no key, or no site id, is rejected.
  3. Confirm grantConsent() runs. The collector buffers events until a consent token is granted, so a missing grant means nothing is sent.
  4. Ensure init() runs on page load. console.log('leadmaps init') right after the call confirms it executed.
  5. Check that DNT (navigator.doNotTrack) is '0' or unset. The SDK is silent under DNT by design.

What’s next

Section titled “What’s next”