The Events API is not available on the Hotjar Basic plan
The Events API is only available for sites on Plus, Business, or Scale plans. To access this feature, follow the steps in this guide to upgrade your Hotjar plan to one of the paid plans mentioned above.
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.
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/team.
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 even name is action_name, but this can be anything you choose. (Example: 'cta_click', 'opened_modal', 'shown_variant_a', etc.)
There are a couple of limitations to be aware of when implementing these events:
- The event name must not exceed 750 characters and can only contain alphanumeric characters (a-z, A-Z, 0-9), underscores (_), and dashes (-).
- You can send up to 1000 events on a Hotjar Site, with an unlimited number of users associated with those events.
If your site is already using the 'trigger' or 'tagRecording' calls, Hotjar will still respect these and they will not stop working. However, we're combining them both into the 'event' call that we will continue building on in the future.
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:
Learn more: How to Use Events for Targeting Hotjar Tools
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.
Combining Event API calls with Identify API calls for targeting Surveys/Incoming Feedback
If you plan on combining Events with User Attribute-based targeting for Surveys or Incoming Feedback, you should ensure that the Identify API call has happened before the Event API call, in your order of execution, bearing 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/Incoming Feedback will not show.
Sending Events after the Hotjar Tracking Code has loaded
The hj() object cannot be accessed until the Hotjar Tracking Code has executed on the page. If for any reason the Event API may be accessed before the tracking code has executed, you can add the following line of code before the Event API code is called:
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. Below are some keyboard shortcuts for a few popular browsers:
Chrome - Cmd+Option+J
Firefox - Cmd+Option+K
Safari - Cmd+Option+C
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.