Events API Reference

Hotjar’s Events API allows you to send events to Hotjar using JavaScript when specific actions take place on your site, saving them inside Hotjar as Events. These events can be used to help you filter collected Recordings and Heatmap data, and to trigger session capture to start or Surveys to appear. 

• Overview
• The Events API call
• Events API call examples
• Best practices
• Testing Events

Overview

Hotjar Events represent actions that a user took while on your site. These events are defined and passed to Hotjar through your client-side code via Hotjar's Events API. This API is available on all pages containing the Hotjar Tracking Code.

With JavaScript, you're able to set up your own criteria to determine what kind of action results in an event being sent to Hotjar. The event could be sent as soon as the page loads, when a modal appears, or when they see a specific variation of the content through an A/B test.

For example, it can be useful to track users who have successfully added a credit card during a checkout process by adding an event like, Added Credit Card successfully. You might also be interested in comparing sessions where a credit card was not added successfully by adding a second event, such as Adding Credit Card failed. By passing events based on user actions, you can filter Recordings by users who triggered each kind of event during their checkout process. Setting up these events in your site's code might look similar to this:

fetch('/api/add-credit-card', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
    hj('event', 'Added Credit Card successfully')
    // handle backend response.
  }
)
.catch(error => {
  hj('event', 'Adding Credit Card failed')
})

*Consult your own developers to determine what code will be needed for your site.

Since the criteria for sending events is based on your own code, the feature is very flexible but will require custom coding from your web developer.

Back to top

The Events API call

Below is the basic format for a call to the Events API:

hj('event', 'action_name');

• The first parameter should always contain the string value event.
• The second parameter is the custom name assigned to your event. In the example above the event name is action_name, but this can be anything you choose. (Example: 'opened_modal', 'shown_variant_a', etc.)

Be aware of the limitations when implementing events

• Naming your Events.

  The event name must not exceed 250 characters and can only contain any of the following: alphanumeric characters (a-z, A-Z, 0-9), underscores (_), dashes (-), spaces, periods(.), colons (:), pipes (|) and forward slashes (/).

• There is a 10,000 unique event limit per Hotjar site.

  Hotjar Filters will only support 10,000 unique events per Hotjar site, with an unlimited number of users associated with those events. If you exceed this, only 10,000 of the most used events (sorted 0-9, a-Z) will be searchable in the interface. This is a rolling total so once the limit is exceeded, some existing events may become unsearchable in the filter. If you exceed the limit, you can delete recordings that contain any events you no longer need. Around 10 minutes after deletion, your event filter list will refresh.

• Only the first 50 unique events in a single session will be searchable by filters.
  To optimize performance, Hotjar will only evaluate the first 50 unique events in a session when determining if a session matches the Event filter criteria. This means that if a session contains 51 unique events, the last unique event that was fired during the session will not be detected if you filtered recordings based on that event. However, all 51 events will still be visible in the recording playback view of each session.
• It's not currently possible to pass any event properties with the event.

Back to top

Events API Call examples

Below are a few example use cases for events.

• Send an event to Hotjar that you can use to trigger a Survey when a user clicks on a Subscribe button.

  hj('event', 'subscribed_to_email_list');
  

• Send an event to Hotjar related to a specific error, so that you can filter your recordings by users who encountered an error during their session.

  hj('event', 'error_occurred');
  

• Send an event to Hotjar to let you know when a user loads a specific page variant during an A/B test.

  hj('event', 'variant_b_displayed');

Back to top

Best practices

• Do not pass Personal Identifying Information as an Event.

  Personal identifying information (PII) should never be used as events in Hotjar. If you'd like to connect session data with specific users, you should explore the User Attributes feature instead.

• If you're also making Identify API calls, these need to be executed before Event API calls.

  You might want to combine Events with User Attribute-based targeting for triggering Surveys. To set this up, the order of execution requires the Identify API call to happen before the Event API call, keeping in mind any asynchronous calls to other services. If the Event API call is executed before the Identify API call has finished execution, the Survey won't show.

• Events cannot be used to collect email or IP addresses, or numbers with 9 or more digits.

  Since there is currently no way to use our User Lookup tool with events, they cannot be used to collect emails, IP addresses, or numbers with 9 or more digits to prevent credit card numbers from being passed to Hotjar. This decision has been based on the General Data Protection Regulation (GDPR). If you'd like to collect email addresses with your user's consent and in line with GDPR, you can do so with User Attributes.

• The Hotjar Tracking Code needs to load before sending any Events.

  The hj() object cannot be accessed until the Hotjar Tracking Code has executed on the page. If the script calling the Events API is added before your Hotjar Tracking Code, there will be an error and the event will not be recognized. If for any reason the Event API is being accessed before the Hotjar Tracking Code has executed, then you can add the following line of code before the Event API code is called:

  window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments);};

• For e-commerce sites, avoid sending specific product information.

  This includes information such as SKU codes. Usually, URLs are more useful and are captured by default.

• Be careful when sending values from objects such as GTM data layers.

  These often hold more data than you expect.

• Avoid passing anything like dates or timestamps.
• Avoid passing anything from URLs such as referral codes.
• Avoid passing detailed errors logs.

Back to top

Testing Events

Following the steps below will allow you to confirm if your Events API calls are successfully received by Hotjar. If you're not familiar with your browser console or developer tools, consider looping in a team member who has more knowledge of these tools or a web developer to assist you.

Enable Hotjar debug logs in your browser console.

Open the page where you want to test the Event and add the ?hjDebug=1 parameter to the end of the URL. Here are a couple of examples of what it might look like:

https://www.example.com/?hjDebug=1
OR
https://www.example.com/?utm_1234&hjDebug=1

Open your browser console.

If you're not familiar with your browser developer tools, or the console, check out this guide to learn how to open your browser console.

Fire the event manually.

To fire your event manually, add the Event API code in your browser console and press Enter or Return on your keyboard. If the event fired successfully, you'll see a confirmation log similar to this:

We also recommend that you go through the steps that your user would, to trigger the event automatically. If the event is fired automatically, then you'll know that your code is implemented successfully.

If the same event is detected when fired manually, but not automatically when testing the user journey, then you may need to revisit your code and criteria that determine when the Event API call is sent.

Back to top