Hotjar enables you to enhance your analysis and insights using our Events API and Identify API. This article gives an overview of Events and User Attributes (which uses the Identify API), and how each API can be used to best serve your goals.
Overview of Events and User Attributes
Events
Events represent the occurrence of something, such as an action or a change that happened on a page. Nearly everything a person does on the web is tied to an event: clicks, scroll, mouse movements, typing, drag and drop, zoom, etc. Some common occurrences that Hotjar Events are used to track include: a modal opened on the page, a user spent x seconds on a page, saw x variant when visiting an A/B test page, encountered a specific error, etc. If you want to react to a change or action triggered by a user, and don't need to store that action against specific users in the future, or use it to trigger other actions later, you can use Hotjar Events.
Events can be used in Hotjar to:
- Trigger session capture for Recordings and Heatmaps.
- Trigger Surveys to appear based on Events.
- Filter Recording and Heatmap data by sessions that contained the event.
To learn more about the Events API and Hotjar Events, see our article on What are Events?
When you're ready to to get started with Events, see our Events API Reference.
User Attributes (Identify API)
User Attributes are data points related to your users, and they can help to tell the history of your users. They describe what your users have done in the past by assigning 'attributes' to the users themselves, rather than just documenting an occurrence within a single session. If you need to keep track of user data over time, including individual user data, and make decisions based on that data, User Attributes are the way to go. These attributes may change over time, but are not bound to a specific session. Some common examples of User Attributes include: email_address, company, name, last_purchase_date, subscription status, on-trial, etc.
User Attributes are the best choice for data such as: the date someone signed up to your site, the last time they signed in, how much they have spent on your product, whether or not they have used a specific feature of your site in the past, etc.
User Attributes can be used in Hotjar to:
- Filter Recordings and Heatmaps data.
- Create Segments of your users.
- Show Surveys only to specific users.
- Lookup and delete user data by user ID.
For a more in-depth understanding of User Attributes, see our article on What are User Attributes?
To get started with User Attributes, we have a step-by-step guide on How to Set Up User Attributes.
Differences between Events and User Attributes
| User Attributes | Events |
| User Attributes require additional Privacy Considerations and your company might require you to sign a DPA with us. It is possible to store Personally Identifiable Information (PII) with User Attributes. | Events don't require additional Privacy Considerations beyond our Acceptable Use Policy and that of your company. It is not possible to store PII with Events |
| User Attributes can trigger Surveys and be used as filters for Recordings and Heatmaps. They're included in Survey exports, and Recording list exports. | Events can trigger Recordings and Surveys. They can also be used as filters for Recordings and Heatmaps. |
| User Attributes store data against specific users, they can single out a user, and potentially identify them. | Events don't store data against specific users, only general data that applies to all users which triggered the Event. |
| User Attributes can do things that require previous knowledge of your users, for example, if you store an attribute called signupDate as a User Attribute, you can use User Attributes as triggers based on that stored attribute. | Events can't do things that require previous knowledge of your users, unless you store that data on your site directly and read from it when you need it. |
| User Attributes enable User Lookup features, allowing the deletion of individual user data as required by some Privacy laws such as GDPR. | Events don't enable User Lookup features and they're not tied to specific users. Deleting an Event call from your site will prevent it from being attached to any subsequent sessions. |
| User Attributes are a bit more complex to setup, they require you to pull data from your database or dataLayer, properly formatting the data, and are stored only when the user session is captured. | Events are simpler to setup, as they don't require more data than what's on the browser at the time the Event fires (a click happens on the browser and can be listened easily with an Event Listener). |
| We recommend firing User Attributes on every page of the flow you're tracking, and some use cases will require you to fire them on every page. | Events only need to be fired on the page you want them to act. |