Plan availability
Available for Recordings and Heatmaps with Observe or Observe Available for Recordings and Heatmaps with Observe
Available for Surveys with Ask or Ask
Hotjar’s Identify API allows you to pass data about your users to Hotjar using Javascript, saving them as User Attributes. These User Attributes can be used by Hotjar to enable advanced filtering and segmentation, giving you quality insights faster than before. You can send up to 100 user attributes on any site, with any number of users associated with those attributes.
User Attributes can be used for filtering Recordings and targeting Surveys, as well as performing user lookup and deletion requests by User ID.
Follow the links below to learn more about User Attributes:
- Overview
- Handling User IDs
- Making calls to Identify
- User Attribute values
- Handling email addresses
- Examples of passing User Attributes to Hotjar
- Using the Identify API in a legally compliant manner
- Disabling User Attributes
- Deleting User Attributes
- Best practices
- FAQs
You can send User Attributes using Google Tag Manager or Segment
It's possible to start sending User Attributes to Hotjar using Google Tag Manager or Segment. For more details, see our How to Send User Attributes with Google Tag Manager article, or if you're using Segment visit our Using Hotjar with Segment guide.
Overview
User Attributes are data values about users of your site passed to Hotjar from your client-side code over Hotjar's Identify API. This API is available on all pages containing the Hotjar Tracking Code.
This data is passed to Hotjar in key-value pairs as an asynchronous AJAX call to Hotjar's servers. These values are associated with a User ID, a uniquely identifiable value passed to Hotjar in your code from a User ID value from your user database. This allows Hotjar to associate data collected about them with the same user ID you use in your own database, as well as lookup user information held on Hotjar about that user.
There are 4 phases to the process of sending User Attributes to and using them with Hotjar.
- Get the data from your site.
- Pass the data into Hotjar via the Identify API.
- Hotjar stores the data about each user as User Attributes against their user_id.
- You can now use Hotjar tools to target and filter by User Attributes.
Making calls to Identify
Before you can begin making calls to Identify, User Attributes must be enabled in your Hotjar settings for each site you want to use User Attributes with.
Enabling and disabling User Attributes
The ability to access the Identify API and User Attributes will be enabled by default if this feature is included in your Hotjar plan. However, if User Attributes were disabled in the past, you may need to re-enable them for use.
On your User Attributes page (Settings > User Attributes), find the Site you want to add User Attributes to using the selection drop-down. You'll see something like this showing the status of your User Attributes implementation:
You are also able to disable User Attributes on this page. Once you have selected a Site with User Attributes enabled, click Disable User Attributes. Once you have done this, further calls to the API will be blocked. The "Disable User Attributes" button will only appear after user attributes data has been received by Hotjar, but not before.
Any reports that rely on User Attributes for targeting purposes will be disabled, and you will not be able to re-enable them unless you change their targeting options, or re-enable User Attributes.
If you want to prevent User Attributes from being sent in the future, you should remove the Identify API code on your site. Once the code is deleted from your site, previously collected User Attributes will still exist, but they will no longer be updated or added to new users to your site.
The API call
Here is the format for a call to the Identify API:
hj('identify', userId, {
user_attribute: value
});
- The first parameter should always contain the string value "identify".
- The second should be a string containing the user id for a user on your site, from your own user database, or null if it is not known.
- The third is a series of key-value pairs inside an object. The key provides the User Attribute name, and the value defines both the type of a User Attribute and its value for that user.
User Attribute names have a maximum length of 50 characters
Hotjar won't properly ingest User Attribute names that are over 50 characters long.
The values passed into this call must come from your own site’s codebase. These values could be pulled directly from your servers or generated client-side.
Once sent to Hotjar, these attributes and the values for each user are stored on Hotjar’s servers. Each time a call to Identify is made, the values stored on Hotjar’s servers will be replaced with the most recent values for these attributes.
You are able to look up all attributes sent to Hotjar in your User Attributes settings page. You can use the User Lookup feature to inspect what values have been passed for a specific user on your site.
As long as a user is identified during their session, Hotjar is then able to both associate User IDs and User Attributes with a session's Recording, and offer fine-grained survey targeting, allowing you to gather targeted feedback from specific users using Surveys. For example: “I want this survey to only target paying customers who made a purchase more than 10 days ago”.
Recordings will be saved against the most recent values sent to Hotjar during the session.
If you send multiple calls to Identify during a user's session, Hotjar will always update with the most recent values. This means that it is important that User IDs and User Attributes are consistently sent with each call, allowing Hotjar to connect a Recording to a specific user.
Handling User IDs
The second argument passed to Hotjar through the Identify API call should be a uniquely identifiable user ID from your own site's database. User Attributes are associated with this User ID.
The User ID should be unique per user but it should not itself contain personal information. It should also be a value that never changes for this user. Once you have set a User ID in Hotjar, it cannot be changed. If it changes, Hotjar will consider this to be a totally new user.
If a User ID is known, the user’s Hotjar ID will be associated with their User ID. A Hotjar ID is a randomly generated unique user ID, created at the Hotjar Site level. If a user does not have a User ID when they visit a site initially, then the Hotjar ID will be then associated with their User ID once the call to the Identify API with a User ID is made.
It’s helpful to work this through with an example.
Let's say we had a user, Rachel. She visits the site 3 times on 2 different devices.
-
Session A - Rachel visits radbooks.com on her tablet.
- She's not a user with the site yet and is assigned a Hotjar ID of 123
-
Session B - Rachel then visits on her mobile.
- She's not a user yet and is assigned a Hotjar ID of 456
-
Session C - Rachel returns to the site from her mobile.
- Hotjar recognizes her with the Hotjar ID of 456.
- She then registers an account.
- Your call to Identify assigns her a User ID of ABC, using the same User ID you have for her in your database.
Because we've associated her with a User ID on your site, we then connect all data associated with Hotjar ID 456 with her User ID of ABC, even though she wasn't logged in during Session B.
If Rachel then goes on to visit the site on her tablet in a 4th session, and this time logs in, Hotjar will then join together data from Session A on Session B, and C, giving you a full picture of her interactions with your site.
What if you don't have a User ID?
If the User ID is not known, then you must pass a value of null to the second parameter. When you do this any User Attributes passed to the Identify API will be associated with the user’s Hotjar ID instead.
Do not pass Personally Identifying Information as a User Attribute without a User ID
If a user id is not known (by passing a null value), then any other User Attributes passed to Hotjar must not contain any personally-identifying information (PII). Your ability to lookup User Attributes associated with an individual user on Hotjar depends on you being able to look up their User ID. Hotjar has no way of retrieving or deleting this data unless you delete the whole Site in Hotjar.
User Attribute values
You can pass the following values to a User Attribute key using the Identify API. Special characters cannot be used at this time.
Handling email addresses
At present, there is one User Attribute key for email addresses: email. Email addresses should be passed as strings to email. For example:
hj('identify', userId, {
email: 'test@test.com'
});
If any other User Attributes of a string type contain an email address, these will be rejected, meaning you should only use `email` to pass email addresses.
Email addresses and User IDs
user_id can take the form of email addresses, so if your database primary key for users is their email address this can be used as a user_id. This should be used only as a last resort. If a user’s primary key in your database exists other than an email, you should use that.
Because email addresses can usually change, if their email address is updated, Hotjar will treat that user as a totally different user. This would prevent you from using User Lookup on the older email address, which may be in breach of your privacy requirements.
Examples of passing User Attributes to Hotjar
Identifying paying customers
Here is an example, where we want to be able to tell Hotjar how much money someone has spent on your site.
hj('identify', userId, {
total_spend: 500
});
Multiple attributes can be passed by adding further key-value pairs into the object. Maybe you wanted Hotjar to know when they first became a customer?
hj('identify', userId, {
total_spend: 500,
first_purchase: '2019-06-20Z'
});
Here we are telling Hotjar that your user became a customer to your service using an ISO8601 date string.
Identifying Attributes for De-identified Users
Sometimes it’s useful to track information about users on your site, even if they aren’t yet users or paying customers. Let’s say you wanted to track the referral source, and landing page A-B test variant a potential lead reached you from:
hj('identify', null, {
ab_test: 'variant-A',
referrer: 'facebook_paid'
});
This would be useful if you wanted to target a survey against users on variant-A, or only those who came to you from Facebook paid adverts, for example.
Using the Identify API in a Legally Compliant Manner
The Identify API is disabled by default, making it easy to avoid accidentally capturing personal information until you have handled privacy concerns appropriately. By enabling User Attributes, you may be passing your end users’ personal data to Hotjar. We require that you acknowledge your legal obligations when doing so and accept Hotjar’s Data Processing Agreement.
It is your responsibility to use this feature in a legally compliant manner, consistent with the laws of your country and countries your users visit from. Visit our privacy page to learn more about Hotjar’s approach to user privacy. When using User Attributes, you should be aware of and conform to Hotjar’s Terms of Service and Acceptable Use Policy.
Handling User Lookup and Deletion Requests
It is possible to lookup and delete a user's data using their User ID. Read more about this in our “How to Use User Lookup” article. It is important to note that if you know a user’s User ID and email address, you should look up their information with both. This is the only way to make sure that all personal information Hotjar has about this user has been looked up & deleted.
Disabling User Attributes
To prevent further User Attributes being sent to Hotjar, you should disable User Attributes.
As long as User Attributes are enabled on your site, if you want to prevent them from being sent in the future, you should remove the code on your site sending them to Hotjar. Once the code is deleted from your site, previously collected User Attributes will still exist, though will no longer be updated or added to new users to your site.
Deleting User Attributes
User Attributes can be deleted from the User Attributes management page by clicking on the trash can icon to the right of the attribute. Only team members with 'Read & Write' permissions or higher can delete User Attributes.
When an attribute is deleted, it will immediately disappear from the Hotjar application. However, the attribute is still stored in the back end for 7 days before being permanently deleted. Data associated with the attribute is ignored during the 7-day period. This is to prevent data from being sent due to caching issues.
If you wish to re-create an attribute that was deleted, you'll need to wait 7 days before the attribute can be re-created successfully.
Be sure to remove any deleted User Attributes from all Identify API calls
Deleting a User Attribute will not remove it from any existing sessions or responses containing it. The attribute will only be removed from filtering and targeting. Remember to remove the deleted User Attribute from all Identify API calls, otherwise, it will reappear in the list.
Best Practices
When to make API calls to Identify
You should make calls to Identify every time:
- A page is loaded with the most recent values (even if they haven’t changed).
- After a URL change in single-page apps.
- Every time a change is made. E.g. if you wanted to track their last purchase in a store, you would want to update this user attribute once a purchase has been made.
Each call will update the User Attributes with Hotjar with the most recent values. When a session Recording ends, the Recording saves the most recent values at the time the session ends. When a call is made, but values have not been updated, the network request will not be sent in order to avoid unnecessary AJAX requests.
Combining Identify API calls with triggers for targeting Surveys
If you plan on combining Events with User Attribute targeting for Surveys, you should ensure that the Identify call has happened before the trigger in your order of execution, bearing in mind any asynchronous calls to other services. If the trigger is executed before the Identify API call has finished execution, the survey will not show.
Queuing calls to the API before Hotjar has loaded
If this script is added before your Hotjar tracking code, there will be an error.
The hj() object cannot be accessed until the Hotjar tracking code tag has executed. If for any reason you access the Identify API before the tracking code has executed you can add the following line of code before the API is called:
window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments)};
Testing User Attributes
There are a few ways you can test if User Attributes are being sent via the Identify API correctly.
- Once the code is live on your page and has been triggered at least once, you can visit your User Attributes settings page to see if the User Attribute captured by Hotjar is active on your page.
- You can enable Hotjar debug mode in your browser to see if Identify API calls are being sent to Hotjar successfully during your session.
- For null value users, you can use any email address you own to consent to connect survey responses with Hotjar tools. This will allow you to see which User Attributes are being passed to unidentified users, which is especially useful in checking you are not accidentally sending PII to Hotjar.