Heatmaps

Heatmaps visualize where users click and how far they scroll on any page of your site.

Enable heatmaps

haya.init('YOUR_SDK_KEY', {
  heatmaps: true,
  autoTrack: {
    clicks: true,    // Required for click heatmaps
    scrolls: true,   // Required for scroll depth heatmaps
  },
});

Both heatmaps: true and the relevant autoTrack flags must be on for heatmap data to be collected.

Click heatmaps

Click coordinates are captured on every click and aggregated into a grid in the dashboard. The darker the spot, the more clicks it received.

The backend rounds coordinates to the nearest 10px to group nearby clicks together, reducing noise and improving visualisation performance.

What's captured per click:

• x, y — position relative to the viewport at time of click
• pageUrl — the page path (e.g. /pricing)
• target — the CSS selector of the clicked element

Scroll depth heatmaps

Scroll depth shows what percentage of the page users actually reach. It answers questions like:

• Does anyone read below the fold?
• At what point do users stop scrolling on the pricing page?
• Is the CTA in the right position?

Scroll depth is captured as a percentage (0–100%) and visualized as a horizontal bar chart bucketed into 10% intervals in the dashboard.

Querying heatmap data

Use the dashboard or call the API directly:

GET /api/v1/analytics/projects/:projectId/heatmap?page=/pricing&from=2024-01-01&to=2024-01-31

Response:

{
  "data": {
    "page": "/pricing",
    "clicks": [
      { "x": 720, "y": 340, "count": 48 },
      { "x": 400, "y": 800, "count": 31 }
    ],
    "scrollDepth": [
      { "_id": 0,  "count": 1240 },
      { "_id": 10, "count": 1180 },
      { "_id": 20, "count": 920 },
      { "_id": 50, "count": 410 }
    ]
  }
}

Top clicked elements

The Elements view in the dashboard ranks every clickable element on a page by how many times it was clicked:

GET /api/v1/analytics/projects/:projectId/elements?page=/pricing&limit=20

Response:

{
  "data": {
    "elements": [
      { "selector": "button#cta-primary", "count": 312 },
      { "selector": "a.nav-pricing",      "count": 140 },
      { "selector": "div.faq-item:nth-child(2)", "count": 87 }
    ]
  }
}

This is useful for understanding which UI elements users actually interact with vs. which ones they ignore.

Data retention

Heatmap data is stored as individual click and scroll events and follows the standard 90-day retention window. After 90 days, old events are automatically deleted via a MongoDB TTL index.