Due to potential security problems inherent to how iframes work, Hotjar is unable to track user interaction on iframe elements embedded on your site. By default, Hotjar's Recordings don't show parts of your site that are contained inside iframes. To display an iframe in a Recording your iframes must first be configured to display in Hotjar, though this will still not allow iframe tracking, and still has limitations.
Even after following the whitelisting advice in this article, these limitations mean the following usually cannot be tracked or displayed in Hotjar Recordings in any case:
❌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.
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.
Until you have enabled iframes inside your Recordings, the iframe content will be shown as a black box with a message telling you that the content is not available in your Recording until you whitelist its iframe.
Enabling iframes to display inside your Recordings is a two-step process:
Check out whitelisting limitations before continuing
It is important to take a look at the section What limitations still exist after whitelisting an iframe? to make sure you'd like to continue whitelisting the iframe inside Recordings.
What limitations still exist after whitelisting an iframe?
Before whitelisting, you should consider some of the limitations that still exist after whitelisting an iframe.
Whitelisting an iframe only allows the iframe to be displayed in a Recording. Here is a complete list of what Hotjar can and cannot capture when an iframe has been whitelisted.
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).
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
Add data-hj-allow-iframe as an HTML attribute to the iframe.
<iframe src="/page.html" data-hj-allow-iframe=""></iframe>
This can be written as ="", 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 whitelisted.
Whitelist the iframe's domain in your Hotjar Site Settings
Before starting on this step, take a look at What limitations still exist after whitelisting an iframe?
Go to site settings by clicking Settings > Sites & Organizations
Click the cog icon next to the site you want to whitelist.
You will see a field where you can insert the domain name you wish to whitelist, under the heading Whitelisted Iframe Domains For Recordings.
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 on the server that the URL points to, other than just serving the iframe content, this could cause unexpected and adverse results.