How to Set Up Events

Events are changes or actions on your site such as clicks, scrolls, and typing. These events can be used with Hotjar to trigger session capture, make Feedback widgets or Surveys appear, or to filter your collected data to find even more insights. This article will look at what’s involved in setting up events with Hotjar using our Events API. 
For an overview of Events and how to use them, see our article on What are Events?

• Step 1 - Identify the main goals you have for your site.
• Step 2 - Decide what events support these goals.
• Step 3 - Implement the Event API code on your site.
• Step 4 - After implementing the Event API code, start using Hotjar Events.

Identify the main goals you have for your site.

Depending on your site, your current goals could include increasing conversions, reducing errors, increasing newsletter subscriptions, or tracking an A/B test. Here are some everyday use cases for Events to help get you started identifying the goals you’d like to focus on:

• Filter Heatmaps to compare the performance of a page variant for A/B testing.
• Filter Recordings where users encountered an error to help find and resolve bugs or common UX issues.
• Trigger a Survey for users who unsubscribe, asking them how you could improve the newsletter.

For more use cases, see our article on What are Events?

Back to top

Decide what events support these goals.

Specific events that are happening (or not happening) on your site can be used to support your goals identified in Step 1. By listing out these events before moving to the next step, you’ll know where to implement the Event API code. Some examples of events on your site include:

• A click event on a specific button or link
  • The Events feature are best used when you want to target a Feedback or Survey tool based on the user's click. Otherwise, consider the built-in Clicked Element Filter instead!
• An error is triggered.
• A page variant is loaded.

You’ll then be able to tie the first two steps together to help with implementing the Event API code in the next step. For example, your goal and event to support the goal could be: “Pass an event to Hotjar when an error is triggered (the event), so that I can filter my Hotjar Recordings by that error event to find and resolve bugs or common UX issues (the goal).”

Back to top

Implement the Event API code on your site.

After working out your goals and the events to support these goals, the next step is implementing the Event API code on your site using the Events API Reference Guide. The Events feature in Hotjar is available and pre-enabled on sites with one of the following plans: Observe or Ask Plus, Business, or Scale. However, some custom code will need to be added to your site to start sending events to Hotjar. Depending on your level of technical expertise, you may need the help of a web developer to write the additional code required.

To help implement the Event API code, we’ve provided further information in our Events API Reference Guide. A snippet of code is available below as an example template for tracking whether or not a credit card was added to a checkout page. This is only an example, so consult with your developers to implement code based on your website and goals.

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.

Back to top

After implementing the Event API code, start using Hotjar Events.

After implementing the Event API code required to send events to Hotjar, you'll begin seeing the events available for use in Hotjar’s tools. From here, you can currently do the following with Hotjar Events:

• Filter Recordings by Events.
• Filter Heatmaps by Events.
• Create a Recording Segment that includes the filtered event.
• Target Surveys and Feedback widgets to trigger based on Events.
• Start session capture based on the triggering of Events.

Back to top

See also

• What are Events?
• [Course] Events for Recordings
• How to Send Events to Hotjar with Google Tag Manager
• Events API Reference
• When to use Events and User Attributes