Tracking API

Add the heft.io script to your site to track page views automatically. Additionally, you can use the JavaScript API to send custom events (e.g. sign-ups, button clicks).

Script tag

Include the lib.js script once in your HTML, ideally in <head> with defer. Replace YOUR-SITE-ID with your site’s UUID from the heft.io dashboard.

<script
  defer
  src="https://track.heft.io/lib.js"
  data-site-id="YOUR-SITE-ID"
></script>

Optional attributes:

data-endpoint — Override the event endpoint URL (default: same origin as the script + /api/event).
data-allow-local — Set to true to send events from localhost or 127.0.0.1 (otherwise the tracker does not send on localhost).
data-track-hash-routing — Set to true to send an additional page view when the URL fragment changes (hashchange). Use for hash-only client routers that do not use the History API. Apps that already use pushState / replaceState for navigation usually do not need this; the tracker deduplicates if the same URL would be reported twice.

The script must be loaded via a <script> tag; it reads data-site-id from that element. Page views are sent on load and on history changes (e.g. client-side navigation).

Custom events

After the script has loaded, call window.heft.track(eventName, properties) to send a custom event.

eventName — string (e.g. 'button-click', 'signed-up').
properties — optional object of string, number, or boolean values (e.g. { label: 'cta', plan: 'pro' }).

// Track simple event
window.heft.track('signed-up');

// Track with additional data
window.heft.track('plan-selected', {
  plan: 'pro'
});

Each call sends one event to your endpoint with the current URL and referrer. Properties are stored with the event for filtering and breakdowns in the dashboard.

Referrer is captured for cross-origin traffic only. Same-origin referrers are intentionally not sent.

Stored page URL

Non-attribution query parameters are removed before the URL is sent. Allowed parameters are ref, source, and the standard utm_* keys. The URL fragment (#...) is kept so it matches the browser (including hash-only routing with data-track-hash-routing).

Disable and enable

To stop tracking (e.g. during local testing or to avoid spamming analytics), call window.heft.disable(). The tracker writes a flag to localStorage so no pageviews or events are sent until you call window.heft.enable() again.

Page visitors can also run window.heft.disable() in the console if they wish to explicitly opt out of heft.io tracking on the site. The flag persists across page loads in the same browser profile. Browsers that block localStorage (e.g. some private-browsing modes) cannot persist the opt-out — a console warning is shown in that case.

// stop sending events
window.heft.disable();

// resume tracking
window.heft.enable();

Both functions log a short message in the console explaining the effect and how to revert.

Last updated: May 2026