Hotjar Heatmaps Integration

Hotjar Heatmaps Integration

Hotjar shows where users click, how they scroll, and where they drop off. Heatmaps, session recordings, and surveys — all through one tracker. Installs in 20 minutes, results visible within hours of launch.

Tracker Installation

Via GTM — recommended method, no code changes needed:

1. GTM → Tags → Create → "Custom HTML"
2. Insert snippet:

<!-- Hotjar Tracking Code -->
<script>
(function(h,o,t,j,a,r){
    h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
    h._hjSettings={hjid:YOUR_SITE_ID,hjsv:6};
    a=o.getElementsByTagName('head')[0];
    r=o.createElement('script');r.async=1;
    r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
    a.appendChild(r);
})(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>

3. Trigger — "All Pages"
4. Publish container

YOUR_SITE_ID is a numeric ID from Hotjar → "Tracking Code".

Direct HTML insertion (if no GTM):

<!-- Before </head> -->
<script>
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:3456789,hjsv:6};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>

NPM (if you need load control):

npm install hotjar-browser

import Hotjar from '@hotjar/browser';
Hotjar.init(YOUR_SITE_ID, 6);

User Identification

Without identification, sessions are anonymous. If you need to filter recordings by specific user or plan:

// After login, send attributes
window.hj('identify', userId, {
    plan: 'pro',
    email: userEmail,
    signup_date: '2024-01-15',
    country: 'RU',
});

Attributes display in Hotjar interface when viewing session recordings — you can filter by plan === 'pro' or signup date.

Events and Tags

Hotjar lets you tag interaction points to later filter recordings:

// User opened form
window.hj('event', 'form_opened');

// User added product to cart
window.hj('event', 'add_to_cart');

// Form validation error occurred
window.hj('event', 'form_validation_error');

// Successful form submission
window.hj('event', 'form_submitted');

In Hotjar interface → "Recordings", you can filter: "show only sessions where form_validation_error occurred" — and see exactly where users struggle.

Heatmap Setup for SPA

In SPA, the router changes URL without full reload. Hotjar creates heatmaps based on URL by default — if URL doesn't change on transitions, all events merge into one map.

Solution — manually notify Hotjar of page changes:

// Vanilla JS / any framework
function notifyHotjarPageChange(newUrl) {
    if (window.hj) {
        window.hj('stateChange', newUrl);
    }
}

// React Router v6
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export function HotjarPageTracker() {
    const location = useLocation();
    useEffect(() => {
        window.hj?.('stateChange', location.pathname + location.search);
    }, [location.pathname]);
    return null;
}

// Next.js
import { useRouter } from 'next/router';
useEffect(() => {
    const handleRouteChange = (url) => window.hj?.('stateChange', url);
    router.events.on('routeChangeComplete', handleRouteChange);
    return () => router.events.off('routeChangeComplete', handleRouteChange);
}, [router.events]);

Protecting Sensitive Data

By default, Hotjar blurs password inputs. For other fields with personal data, explicitly specify classes:

<!-- Field hidden in Hotjar recordings -->
<input type="text" name="card_number" class="data-hj-suppress">

<!-- Block completely hidden -->
<div class="data-hj-suppress">
    <p>SSN: 123-45-6789</p>
</div>

<!-- Alternative attribute -->
<input data-hj-suppress type="text" name="passport">

In Hotjar site settings, you can set global CSS selectors for suppression — no code changes needed.

Surveys and NPS via Hotjar API

// Open specific survey programmatically
window.hj('trigger', 'survey_trigger_name');

// Example: show survey after successful order
function onOrderCompleted(orderId) {
    window.hj?.('event', 'purchase_completed');
    window.hj?.('identify', userId, { last_order_id: orderId });

    // Show survey after 5 seconds
    setTimeout(() => window.hj?.('trigger', 'post_purchase_survey'), 5000);
}

Verification

• Hotjar → "Tracking" → status should be "Verified"
• DevTools → Network: look for requests to hotjar.com — should pass without errors
• Hotjar → "Recordings" — after first real sessions (usually 1–2 hours), recordings appear
• Quick check: Hotjar → "Tools → Incoming Feedback" — you can see your visit

Timeline

Installing tracker via GTM — 30 minutes. Setting up user identification and events — 2–3 hours. Data masking setup + SPA testing — 1–2 more hours.