Hotjar Event Tracking | Blue Frog Docs

Hotjar Event Tracking

Complete guide to Hotjar event tracking, custom events, identify API, and user attributes

Hotjar Event Tracking

Overview

Event tracking in Hotjar allows you to capture and analyze specific user interactions beyond standard page views. While Hotjar automatically tracks page loads and user sessions, custom events let you monitor actions like button clicks, form submissions, feature usage, or any interaction that matters to your business.

Unlike traditional analytics platforms where events drive the entire data model, Hotjar uses events to trigger and filter recordings, heatmaps, and surveys. This makes event tracking a powerful tool for focusing your analysis on the moments that matter most.

How Hotjar Events Work

Hotjar events serve three main purposes:

  1. Trigger recordings: Start recording sessions when specific events occur
  2. Filter insights: Segment heatmaps and recordings by user actions
  3. Activate surveys: Display surveys to users based on their behavior

Events in Hotjar are lightweight and designed to complement visual insights rather than replace them. You're not building complex event taxonomies like in Mixpanel or Amplitude; you're marking key moments that help you understand user behavior in context.

Event Types

Page Views (Automatic)

Hotjar automatically tracks page views when users navigate your site. No configuration required. Each page view can trigger recordings based on your settings and contributes to heatmap data.

Custom Events

Custom events are user-defined interactions that you track via JavaScript. Common examples include:

  • Button clicks (e.g., "Add to Cart", "Download", "Sign Up")
  • Form submissions or abandonment
  • Video plays or completions
  • Feature usage milestones (e.g., "First Project Created")
  • Error states or warnings
  • Navigation menu interactions

Implementing Custom Events

Basic Event Tracking

Use the hj function to send custom events to Hotjar:

// Basic event
hj('event', 'button_clicked');

// Event triggered on user action
document.getElementById('signup-button').addEventListener('click', function() {
  hj('event', 'signup_button_clicked');
});

Events with Context

While Hotjar doesn't store event parameters like traditional analytics platforms, you can use event names to capture context:

// Include context in event name
hj('event', 'newsletter_signup_homepage');
hj('event', 'download_pricing_pdf');
hj('event', 'video_play_product_demo');

// Or segment by user action
if (userType === 'premium') {
  hj('event', 'premium_feature_accessed');
} else {
  hj('event', 'free_feature_accessed');
}

Form Tracking Events

Track form interactions to understand where users drop off:

// Form start
document.querySelector('form').addEventListener('focus', function(e) {
  if (e.target.matches('input, textarea, select')) {
    hj('event', 'checkout_form_started');
  }
}, true);

// Form submission
document.querySelector('form').addEventListener('submit', function() {
  hj('event', 'checkout_form_submitted');
});

// Form abandonment (user leaves page without submitting)
window.addEventListener('beforeunload', function() {
  if (!formSubmitted) {
    hj('event', 'checkout_form_abandoned');
  }
});

E-commerce Tracking

Monitor key shopping behaviors:

// Add to cart
function addToCart(productId, productName) {
  // Your add-to-cart logic
  hj('event', 'add_to_cart');
}

// Checkout initiated
hj('event', 'checkout_started');

// Purchase completed
hj('event', 'purchase_completed');

// Cart abandoned
hj('event', 'cart_abandoned');

Error & Exception Tracking

Capture when users encounter issues:

// Track errors
window.addEventListener('error', function(e) {
  hj('event', 'javascript_error_occurred');
});

// Track form validation errors
if (!isValid) {
  hj('event', 'form_validation_error');
}

// Track API failures
fetch('/api/data')
  .catch(function() {
    hj('event', 'api_request_failed');
  });

Using Events with Google Tag Manager

For teams using GTM, you can trigger Hotjar events via the data layer:

Setup

// Push event to dataLayer
dataLayer.push({
  'event': 'customEvent',
  'eventCategory': 'User Action',
  'eventAction': 'Button Click',
  'eventLabel': 'CTA Homepage'
});

GTM Custom HTML Tag

Create a Custom HTML tag in GTM:

<script>
  hj('event', {{Event Label}});
</script>

Trigger: Custom Event matching your dataLayer event name

This approach keeps event tracking centralized in GTM, making it easier to manage without code deployments.

Identify API: Tracking User Attributes

The Hotjar Identify API allows you to associate user data with sessions. This helps you filter recordings and analyze behavior by user type, subscription level, or any custom attribute.

Basic Identify Call

// Identify user with attributes
hj('identify', 'USER_ID', {
  'email': 'user@example.com',
  'plan': 'premium',
  'signup_date': '2024-01-15',
  'account_type': 'enterprise'
});

User Attributes

Common attributes to track:

  • User ID: Unique identifier (required)
  • Email: For support and outreach context
  • Plan/Tier: Free, trial, premium, enterprise
  • Account Age: New, returning, long-term
  • User Role: Admin, editor, viewer
  • Custom Properties: Industry, company size, feature flags

Identify on Login

Trigger the identify call when users log in:

function onUserLogin(user) {
  hj('identify', user.id, {
    'email': user.email,
    'plan': user.subscriptionPlan,
    'role': user.role,
    'company': user.companyName,
    'signup_date': user.createdAt
  });
}

Single-Page Applications (SPAs)

For SPAs, call hj('identify') after each route change or authentication state update:

// React example
useEffect(() => {
  if (currentUser) {
    hj('identify', currentUser.id, {
      'plan': currentUser.plan,
      'user_type': currentUser.type
    });
  }
}, [currentUser]);

// Vue example
watch(user, (newUser) => {
  if (newUser) {
    hj('identify', newUser.id, {
      'subscription': newUser.subscription,
      'account_status': newUser.status
    });
  }
});

Anonymous vs Identified Users

Hotjar can track both anonymous and identified users. Anonymous sessions are valuable for understanding general behavior, while identified sessions help you:

  • Filter recordings by user segment
  • Understand how specific user types interact
  • Provide context for support and research
  • Analyze behavior across multiple sessions

Triggering Recordings with Events

Events can automatically start Hotjar recordings when specific actions occur.

Enable Event-Based Recording

  1. Go to Recordings in Hotjar
  2. Create or edit a recording
  3. Under Advanced filters, select Track only sessions where
  4. Choose Event happens and enter your event name

Example: Only record sessions where users trigger checkout_started

This ensures you're not wasting recording quota on irrelevant sessions.

Multiple Event Triggers

You can combine multiple events:

  • Record if signup_button_clicked OR trial_started
  • Record if error_occurred AND form_submitted

This flexibility helps you capture exactly the sessions you need for analysis.

Filtering Heatmaps by Events

Heatmaps can be segmented by events to show behavior from specific user actions.

Steps:

  1. Navigate to Heatmaps in Hotjar
  2. Select the page you want to analyze
  3. Click Filters
  4. Add Event filter and select your custom event

Example: View heatmap only for users who triggered purchase_completed to see how successful buyers interact with your product page.

Triggering Surveys with Events

Events can display surveys at the perfect moment in the user journey.

Setup:

  1. Go to Surveys in Hotjar
  2. Create a new survey or edit existing
  3. Under Targeting, select Show survey when event happens
  4. Enter your event name

Examples:

  • Show NPS survey after purchase_completed
  • Ask for feedback after onboarding_finished
  • Trigger exit survey when subscription_cancelled

This context-aware surveying dramatically improves response rates and data quality.

Event Naming Best Practices

Use Descriptive Names

✅ Good:

  • checkout_form_submitted
  • pricing_page_cta_clicked
  • video_play_product_demo

❌ Avoid:

  • event1
  • click
  • btn

Be Consistent

Choose a naming convention and stick to it:

  • snake_case: add_to_cart, form_submitted
  • camelCase: addToCart, formSubmitted
  • kebab-case: add-to-cart, form-submitted

Use prefixes to organize events:

  • form_start, form_field_error, form_submitted
  • video_play, video_pause, video_complete
  • checkout_start, checkout_payment, checkout_complete

Avoid Dynamic Values in Event Names

❌ Don't:

hj('event', 'product_' + productId + '_viewed'); // Creates too many unique events

✅ Do:

hj('event', 'product_viewed'); // Use attributes or identify API for context

Debugging Events

Browser Console

Check if events are firing correctly:

// Enable Hotjar debug mode
localStorage.setItem('hjDebug', 'true');

// Trigger your event
hj('event', 'test_event');

// Check console for confirmation

Chrome DevTools

Monitor network requests to Hotjar:

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Filter by hotjar.com
  4. Trigger your event
  5. Look for a request containing your event name

Hotjar Dashboard Validation

After implementing events:

  1. Navigate to your site and trigger the event
  2. Wait a few minutes for data to process
  3. Go to Hotjar dashboard > Recordings
  4. Filter by your custom event
  5. Confirm recordings appear

Common Use Cases

SaaS Onboarding

Track milestone completion to understand where users drop off:

hj('event', 'onboarding_step_1_complete');
hj('event', 'onboarding_step_2_complete');
hj('event', 'onboarding_step_3_complete');
hj('event', 'onboarding_completed');

Content Engagement

Monitor how users interact with your content:

// Time on page
setTimeout(() => hj('event', 'spent_30_seconds_on_page'), 30000);

// Scroll depth
window.addEventListener('scroll', function() {
  let scrollPercent = (window.scrollY / document.body.scrollHeight) * 100;
  if (scrollPercent > 75 && !scrollTracked) {
    hj('event', 'scrolled_75_percent');
    scrollTracked = true;
  }
});

Feature Adoption

Understand which features resonate:

hj('event', 'feature_dashboard_viewed');
hj('event', 'feature_export_used');
hj('event', 'feature_share_clicked');

Support & Feedback

Track when users seek help or encounter issues:

hj('event', 'help_center_opened');
hj('event', 'live_chat_started');
hj('event', 'feedback_widget_opened');

Limitations & Considerations

Event Quotas

Hotjar doesn't limit the number of events you can send, but excessive events can:

  • Slow down page performance
  • Make filtering overwhelming
  • Consume recording quota faster

Aim for quality over quantity: track meaningful interactions, not every mouse movement.

No Historical Data

Events are only tracked going forward. Unlike some platforms, you can't retroactively analyze events you didn't set up.

No Event Properties

Hotjar events don't support parameters like { product_id: '123', price: 49.99 }. Use descriptive event names or the Identify API to add context.

Privacy & Compliance

  • Don't send PII (personally identifiable information) in event names
  • Use the Identify API for user attributes and ensure you have consent
  • Review Hotjar's data processing agreement for GDPR/CCPA compliance

Best Practices Summary

✅ Do:

  • Track key user actions that map to business goals
  • Use clear, descriptive event names
  • Test events in staging before deploying to production
  • Combine events with Identify API for richer context
  • Use events to filter recordings and target surveys
  • Document your event taxonomy for team alignment

❌ Don't:

  • Track every possible interaction (focus on what matters)
  • Include PII in event names or attributes
  • Use dynamic values in event names
  • Assume events work without testing
  • Forget to update events when site functionality changes

Additional Resources:

↑ Back to top
// SYS.FOOTER