Hotjar cannot track iframes, due to potential security problems inherent to how iframes work. By default, Hotjar's Recordings do not show parts of your site that are contained inside iframes. You will instead see the space where your iframe content would be as an element with a black background and a message stating that Hotjar cannot track iframes embedded on your page.
If you're unfamiliar with iframes, you can think of them as web pages inside web pages. They are often used to add elements like chatbots, videos, or forms to your pages by third-party services. You can read more about them in the Mozilla Developer Network documentation.
Hotjar offers the ability to have your iframes load inside the recordings player. This does not mean that Hotjar can track iframes: only that you can load the page HTML for an iframe inside the recording player. No JavaScript will be executed. This means the following content types cannot be captured within Hotjar Recordings:
❌Chatbots
❌Third-party video players (such as YouTube or Vimeo)
❌Third-party forms (for example, Typeform forms)
❌Web-apps that are loaded via iframes
❌Most third-party payment systems
❌Most third-party content
Enabling self-hosted iframes to display inside your Recordings is a two-step process:
- Adding an HTML attribute to the iframe
- Allowing iframes domain in your Hotjar Site Settings
Check out allowing iframe limitations before continuing
It is important to take a look at the section What limitations still exist after allowing an iframe? to make sure you'd like to continue allowing the iframe inside Recordings.
What limitations still exist after allowing an iframe?
Before allowing an iframe, you should consider some of the limitations that still exist even after allowing the iframe.
We can track:
✔️ a static page delivered through an iframe can be displayed inside a Recording.
✔️ mouse over behavior is tracked, relative to the parent page.
We cannot track:
❌ clicks on elements inside an iframe.
❌ scroll events inside an iframe.
❌ typing input inside an iframe.
❌ DOM mutation events.
❌ CSS animations dependent on user input (such as hovering over a button).
Additionally:
❌ JavaScript will not be executed.
These limitations mean that many third-party iframes, such as video players, chatbots, forms, and so on, may not display properly, even once allowed, because they rely on JavaScript to properly display.
If you'd like to record interactions happening inside of an iframe you can put the Hotjar Tracking Code in the head element of the iframe source page, but you must also remove the Tracking Code on the parent page.
Having the Hotjar Tracking Code on both the source page and the page containing the iframe can cause Recordings of the page to fail and data collection to be skewed.
Adding an HTML attribute to the iframe
If your iframe is not a third-party iframe and is hosted on your site, you can add an HTML attribute to make viewing the content within your Recordings possible. Movement and input data will still not be captured.
An iframe source page will reload each time it's displayed in a Recording playback
The URL that the iframe points to is stored on our servers and reloaded every time a recording is played in the Hotjar dashboard. This means that if loading the iframe source page triggers some additional behavior, this could cause unexpected and adverse results.
Add data-hj-allow-iframe as an HTML attribute to the iframe.
You can do this by adding an HTML attribute, data-hj-allow-iframe, to the iframe you wish to display.
<iframe src="https://example.com/page.html" data-hj-allow-iframe=""></iframe> This can be written as data-hj-allow-iframe="", data-hj-allow-iframe="true", or just data-hj-allow-iframe. Either way, the value will show as "true" on the backend.
This attribute has to be placed in the iframe element itself
The attribute cannot be placed in the parent element of the iframe. Many third-party tools do not allow you to edit their iframe elements, which means that they cannot be allowed.
Before starting on this step, take a look at What limitations still exist after allowing an iframe?
Go to site settings by clicking Settings > Sites & Organizations
Click the cog icon next to the site you want to allow.
You will see a field where you can insert the top-level domain name you wish to allow, under the heading Allowed iframe Domains For Recordings.
Under Session targeting and tracking add the domain name.
When entering domain names into the ALLOWED IFRAME DOMAINS field, only enter the top-level domain. This is the domain without www, http://, or https:// connected to it. For example, if you wanted to allow https://www.hotjar.com/ to this field, the top-level domain would be hotjar.com
Click Save Changes