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 tracker.js 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/tracker.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.

UTM parameters

The tracker supports the standard UTM query parameters on page URLs and referrers:

utm_source
utm_medium
utm_campaign
utm_content
utm_term

UTM parameters can appear in any order. For stable reporting, utm_source and utm_medium are normalized to lowercase with spaces replaced by underscores.

Attribution uses page URL values first, and falls back to referrer URL values when a UTM field is missing on the page URL.

To avoid partial attribution noise, if any utm_* parameter is present but either utm_source or utm_medium is missing, that partial UTM set is ignored.

// good: complete UTM set
https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_launch

// ignored UTM set: missing utm_source
https://example.com/pricing?utm_medium=email&utm_campaign=welcome

Stored page URL

Non-attribution query parameters are removed before storage. Allowed parameters are ref and the UTM keys listed above. The URL fragment (#...) is kept on the stored URL 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 sets a cookie 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.

// 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: April 2026