Getting started overview

Hotjar is a product experience insights platform that uses tools like heatmaps, session recordings, and surveys to help understand user behavior on websites. Getting started with Hotjar primarily involves embedding a JavaScript tracking code into your website. This code collects data on user interactions, which is then processed and visualized within the Hotjar dashboard. While Hotjar offers a public API for data export and integration, initial setup focuses on client-side data collection via the tracking script.

The process generally follows these steps:

  1. Create a Hotjar account.
  2. Add your website (referred to as a 'Site') to your Hotjar account.
  3. Retrieve the unique Hotjar tracking code for your Site.
  4. Embed the tracking code into the <head> section of all pages you wish to track.
  5. Verify the tracking code installation.
  6. Generate initial user activity on your site to populate data.

The following table provides a quick reference for the initial setup steps:

Step What to do Where
1. Account Creation Sign up for a new Hotjar account. Hotjar pricing page
2. Add Site Register your website domain within Hotjar. Hotjar dashboard > Sites & Organizations
3. Get Tracking Code Locate the unique JavaScript snippet. Hotjar dashboard > Sites & Organizations > Tracking Code
4. Embed Code Paste the snippet into your website's HTML. Your website's <head> section (or via Tag Manager)
5. Verify Installation Confirm the code is active and data is flowing. Hotjar dashboard > Sites & Organizations > Tracking Code Status
6. Generate Activity Browse your website to create initial data points. Your website

Create an account and get keys

To begin, navigate to the Hotjar website and select a plan. A free Basic plan is available, supporting up to 35 sessions per day. Paid plans, such as the Plus plan, start at $32 per month when billed annually, offering 100 sessions per day and additional features. During the signup process, you will be prompted to provide an email address and create a password. After account creation, you will typically be guided to add your first 'Site'.

When you add a new Site, Hotjar will prompt you to enter the website's URL. Once the site is added, Hotjar generates a unique JavaScript tracking code snippet. This snippet contains your Site ID, which acts as the identifier for all data collected from that specific website. There are no traditional API keys issued for client-side tracking; instead, the Site ID embedded within the JavaScript snippet serves this purpose.

You can find this tracking code within your Hotjar dashboard by navigating to Sites & Organizations, selecting your site, and then clicking on Tracking Code. The code will resemble the following structure, with YOUR_SITE_ID replaced by your unique identifier:

<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-','f.js?sv=');
</script>

This snippet must be placed within the <head> tag of every page on your website that you intend to track. For content management systems (CMS) like WordPress or Shopify, Hotjar provides specific installation guides. Alternatively, tag management systems such as Google Tag Manager can be used to deploy the Hotjar tracking code without directly modifying website code. Using a tag manager can simplify deployment and management, as described in Google's Tag Manager documentation.

Your first request

Hotjar's primary data collection mechanism is passive; it doesn't involve making explicit API requests from your server or client-side code for initial setup. Instead, the embedded JavaScript snippet automatically begins collecting data once it's correctly installed and your website loads in a user's browser.

To perform your "first request" and verify data collection, you need to:

  1. Embed the Tracking Code: Ensure the Hotjar tracking code (obtained in the previous step) is present in the <head> section of your website.
  2. Visit Your Site: Open your website in a browser. Navigate through a few pages and interact with elements to generate some user activity. This will trigger the Hotjar script to record a session.
  3. Verify Installation: Return to your Hotjar dashboard. Navigate to Sites & Organizations > your site > Tracking Code. Hotjar provides an installation status indicator that typically changes from 'Not installed' to 'Tracking code installed' once it detects activity.
  4. Check for Data: After a few minutes, visit the Recordings or Heatmaps sections in your Hotjar dashboard. You should start seeing new session recordings or heatmap data appearing, indicating successful data collection. If you have just installed Hotjar, it may take a few minutes for the first recordings to appear.

The Hotjar tracking code automatically sends data to Hotjar's servers whenever a user interacts with a page where the code is present. This includes page views, clicks, scrolls, and form interactions, all without requiring manual API calls from your end for basic data capture.

Common next steps

Once the Hotjar tracking code is installed and confirmed to be collecting data, several common next steps can enhance your understanding of user behavior:

  • Configure Heatmaps: Hotjar automatically generates heatmaps for pages with sufficient traffic. You can access these from the Heatmaps section of your dashboard. Consider creating specific heatmaps for key landing pages or conversion funnels to analyze user attention and click patterns.
  • Review Session Recordings: Watch initial session recordings to observe how users navigate your site, where they encounter issues, or what draws their attention. Recordings provide qualitative insights that complement quantitative data.
  • Set Up Surveys: Create and deploy custom surveys or feedback widgets to gather direct user feedback. Hotjar offers various survey types, including on-site polls and external survey links. Refer to the Hotjar Surveys documentation for detailed setup instructions.
  • Integrate with Other Tools: Hotjar offers integrations with various analytics and collaboration tools. For instance, you can integrate with Google Analytics to combine quantitative data with Hotjar's qualitative insights.
  • Define Events: For more granular tracking, you can define custom events using Hotjar's Events API. This allows you to track specific user actions that are not automatically captured, such as interactions with custom components or specific button clicks. This requires adding a small JavaScript function call to your site's code, such as hj('event', 'your_event_name');.
  • Explore the Hotjar API: For advanced use cases, the Hotjar API allows you to export collected data or integrate Hotjar into custom workflows. This API is primarily for server-side data extraction rather than client-side interaction.
  • Understand Data Privacy: Review Hotjar's GDPR and CCPA compliance documentation to ensure your data collection practices align with privacy regulations. Hotjar provides features for suppressing sensitive data and managing user consent.

Troubleshooting the first call

If your Hotjar tracking code isn't collecting data, consider the following troubleshooting steps:

  • Verify Code Placement: Ensure the Hotjar tracking code is placed directly within the <head> section of your HTML, not in the <body> or <footer>. Incorrect placement can prevent the script from loading correctly.
  • Check for Typos: Double-check that the entire snippet was copied correctly, including your unique Site ID. Any small error can break the script.
  • Browser Developer Tools: Open your browser's developer console (usually F12 or Cmd+Option+I) and check the "Network" tab for requests to static.hotjar.com or ws.hotjar.com. Look for any JavaScript errors in the "Console" tab. A successful Hotjar installation will typically show network requests to these domains.
  • Ad Blockers/Browser Extensions: Temporarily disable any ad blockers or privacy-focused browser extensions. These can sometimes prevent tracking scripts from loading.
  • Firewall/CSP Issues: If you have a strict Content Security Policy (CSP) or firewall, ensure that static.hotjar.com and ws.hotjar.com are whitelisted. For details on how to configure a CSP, refer to Mozilla's Content Security Policy guide.
  • Cache Clearing: Clear your browser's cache and your website's cache (if applicable) after installing the code. This ensures you're loading the latest version of your website.
  • Hotjar Debugger: Hotjar offers a browser extension called the "Hotjar Debugger" that can help identify issues with your tracking code installation. It provides real-time feedback on whether Hotjar is detecting activity on your page.
  • Site ID Mismatch: Confirm that the Site ID in your tracking code snippet matches the Site ID displayed in your Hotjar dashboard for the site you are trying to track.
  • Check Sampling Settings: On paid plans, ensure that session sampling settings are not preventing data collection. While not common for initial setup, it's a consideration for ongoing data flow.
  • Refer to Hotjar Help: If issues persist, consult the Hotjar tracking code troubleshooting guide for specific solutions and contact their support.