Skip to main content

Auto-Tracking

Haya automatically captures the most important user interactions with zero configuration beyond haya.init().

What gets tracked​

Clicks​

Every click on the page is recorded with:

  • x / y — cursor coordinates relative to the viewport
  • target — CSS selector of the clicked element (e.g. button#submit)
  • text — visible text of the clicked element (truncated to 100 chars)
  • pageUrl — path of the page where the click happened

Clicks are the primary data source for heatmaps and top elements in the dashboard.

Disable:

haya.init('YOUR_SDK_KEY', {
  autoTrack: { clicks: false },
});

Scrolls​

Scroll depth is captured as a percentage (0–100%) of total page height, throttled to one event every 200ms. This powers the scroll depth heatmap in the dashboard.

Example payload:

{
  "type": "scroll",
  "payload": {
    "scrollDepth": 62,
    "scrollY": 1840,
    "pageHeight": 2968
  }
}

Disable:

haya.init('YOUR_SDK_KEY', {
  autoTrack: { scrolls: false },
});

Pageviews​

A pageview event fires:

  1. On initial page load
  2. On every client-side navigation (pushState, replaceState, popstate)

This means Haya works correctly with single-page apps (React Router, Vue Router, Next.js App Router, etc.) without any extra configuration.

Example payload:

{
  "type": "pageview",
  "payload": {
    "url": "https://myapp.com/pricing",
    "referrer": "https://myapp.com/features"
  }
}

Disable:

haya.init('YOUR_SDK_KEY', {
  autoTrack: { pageviews: false },
});

Form interactions​

Focus, blur, and submit events on form fields are tracked automatically. Field values are never captured.

Example payload (blur event):

{
  "type": "form_interaction",
  "payload": {
    "action": "blur",
    "field": "input#email",
    "formId": "signup-form"
  }
}

Form interaction tracking is always on when the SDK is initialized. There is no separate toggle — to disable it, use ignoreSelectors to exclude specific forms:

haya.init('YOUR_SDK_KEY', {
  ignoreSelectors: ['form#payment-form'],
});

Mouse movement (optional)​

Mouse cursor position is off by default because it generates very high event volume. Enable only if you need cursor tracking:

haya.init('YOUR_SDK_KEY', {
  trackMousemove: true,
});

Mouse positions are throttled to one event every 100ms.

Excluding elements​

Use ignoreSelectors to prevent tracking on specific elements:

haya.init('YOUR_SDK_KEY', {
  ignoreSelectors: ['.no-track', '#admin-panel', '[data-haya-ignore]'],
});

Or add the haya-ignore class to any element in your HTML:

<button class="haya-ignore">Internal button</button>

Session boundaries​

All events are tied to a session ID. A session starts when the user arrives on your site and expires after 30 minutes of inactivity. If the user comes back after 30 minutes, a new session is created automatically.

The session ID is stored in localStorage so it persists across page refreshes within the same session.