You can send Events using Google Tag Manager, Google Analytics, or Segment
It's possible to start sending Events to Hotjar using Google Tag Manager, Google Analytics, or Segment. For more details, see our How to Send Events with Google Tag Manager article, Using Hotjar with Google Analytics, or if you're using Segment visit our Using Hotjar with Segment guide.
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.
For example, it can be useful to track users who’ve clicked on a CTA button with an event. Perhaps you’re interested in diagnosing why people are not clicking on it. By passing an event, you can filter Recordings by users who have not clicked on your call to action. Setting this up in your site's code could look something like this:
document.querySelector('#my-button') .addEventListener('click', () => hj('event', 'clicked_cta'));
If your site is already using the 'trigger' or 'tagRecording' calls, Hotjar will still respect these and they will not stop working. However, a 'trigger' will not be searchable in Recordings filters, and a 'tag' cannot be used for targeting Hotjar tools.
The Events API call
Below is the basic format for a call to the Events API:
- 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: 'cta_click', '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 alphanumeric characters (a-z, A-Z, 0-9), underscores (_), and dashes (-).
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.
It's not currently possible to pass any event properties with the event.
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.
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.
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 or Feedback. 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 or Feedback widget 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:
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.
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:
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.