In this article, we'll explain how Hotjar interacts with iframes, the limitations that exist, and the settings/features that are available.
- Understanding iframes within Hotjar
- What are my options to track iframe content with Hotjar?
- What limitations exist after allowing an iframe?
- How to allow an iframe within Hotjar
Understanding iframes within Hotjar
An iframe can be described as a web page that appears inside of another web page. They are often used to embed content from third-party websites, such as chatbots, videos, or forms. However, they can also be used to show content from the same website domain.
To determine where an iframe's content is coming from, we can look at the iframe source URL (src=""), which is shown in the code like this:
<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe> In the example above, the iframe source URL is coming from YouTube.
You can learn more about iframes in the Mozilla Developer Network documentation.
To get the most out of this article, it's important to know these terms:
-
iframe 'parent' page - This is the page where the <iframe> code has been added. This page usually has its own content but also includes the embedded iframe content. It is the page that your users will visit in their browser.
Example of an iframe parent page (https://www.hotjar.com). -
iframe 'source' page - This is the page where the iframe content is coming from. The source page URL is usually not a page that your users would access directly.
Example of the corresponding iframe source page. (https://Hotjar.eu.ada.support)
Hotjar doesn't track iframes embedded on your page by default
Out of the box, Heatmaps and Recordings will block iframe elements that are included in session data and prevent them from rendering content. Instead of the iframe content, while watching a recording or viewing a heatmap, you'll see a message stating that Hotjar cannot track iframes embedded on your page:
What are my options to track iframe content with Hotjar?
Hotjar is only able to track webpages where the Hotjar tracking code (tracking code) is installed. If the tracking code is installed on the iframe's parent page, then the tracking code will track that page, but it won't track or display interactions within the iframe (the iframe source page content).
The same is true vice versa. If the tracking code is installed within the iframe source page, it will track and display interactions for the source page, but it will not track or display interactions on the iframe's parent page.
Hotjar can be used to track iframe content in the following ways, we'll outline each one in the paragraphs below:
- Install the tracking code only on the iframe parent page
- Install the tracking code only on the iframe source page
- Install the same tracking code on both the iframe parent & source pages
Considerations when attempting to install the Hotjar tracking code within an iframe.
To track interactions within an iframe, you'll need to have access to edit the code of the iframe's source page. If using an iframe that is from a third party, this may not be possible. If the third party allows you to add your tracking code to the source page of their iframe content, they will also need to factor Hotjar tracking into their privacy and cookie policies.
Install the tracking code only on the iframe parent page
With this approach, Hotjar will track the page content of the parent page, but no interactions will be tracked inside the iframe.
In recordings and heatmaps, the iframe will be blocked by default, and if you allow the iframe to appear, you will see a static version of the iframe source page content, but Hotjar will not track any interactions within the iframe. Learn how to allow an iframe.
Install the tracking code only on the iframe source page
With this approach, Hotjar will track the page content of the iframe's source page, but no interactions will be tracked on the parent page.
In recordings and heatmaps, you will see the parent page that was actually visited by the user, but you'll only see data collection based on interactions that occurred within the iframe element. Any interactions the user had with the parent page outside of the iframe will not be tracked.
Install the same tracking code on both the iframe parent & source pages
With this approach, Hotjar will be able to detect data from both the parent page and the iframe source page. However, this is only possible if your team is able to edit the code from the iframe source page directly (this is rarely possible if using an iframe provided by a third party).
If you are able to add the tracking code to your iframe source page and the parent page, it's important to know that the iframe content will be treated as a separate page within Hotjar recordings. Instead of seeing both the parent and source page interactions at the same time, Hotjar will treat interactions with the iframe as another tab in the user's session.
This will cause the recording to look like the user is clicking back and forth between the iframe parent page and the iframe source page instead of seeing both of them at the same time. Due to the limitations around iframes, it is not possible to prevent this behavior when the tracking code is added to both the parent and source pages at the same time.
What limitations exist after allowing an iframe?
Before allowing an iframe, consider the limitations that will persist even after allowing the iframe:
- The iframe must have a src attribute.
- Hotjar cannot allow an iframe if its src attribute uses a relative page path (Example: src=“/page”) instead of the complete URL (Example: src=“https://hotjar.com/page”).
- JavaScript will be blocked within the iframe if recording the parent page.
- Interactions (click and scroll events, typing, CSS animations, DOM mutations, etc.) will not be tracked in the iframe if recording the parent page.
These limitations mean that most third-party iframes may not display because they rely on JavaScript, even after allowing the iframe. Some examples of content types that won't work with an allowed iframe include:
- Chatbots
- Third-party video players (including YouTube and Vimeo)
- Third-party forms (including Typeform forms)
- Most third-party web-apps that are loaded via iframes
- Most third-party payment systems
This means that Hotjar can only show the following aspects of an allowed iframe:
- Static page content (without JavaScript) loading through an iframe.
- Cursor behavior is tracked relative to the parent page.
How to allow an iframe within Hotjar
Hotjar offers the ability to 'allow' iframes to appear inside heatmaps and recordings. In most cases, this means Hotjar can only load the iframe page, but can't track user interactions within the iframes unless you have the ability to add the tracking code to both the source page and the iframe. If JavaScript is required for the iframe content to load, allowing the iframe may result in the iframe being shown as an empty space in recordings and heatmaps.
Before allowing iframes on your Hotjar Site, review the next section in this article that outlines the limitations that may prevent iframes from being displayed in Hotjar.
Add data-hj-allow-iframe as an HTML attribute to your 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 must be placed in the <iframe> element itself and 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 they cannot be allowed.
An iframe source page will reload each time it's displayed within Hotjar
The URL that the iframe points to is stored on our servers and reloaded every time a recording is played. This means that if loading the iframe source page triggers some additional behavior, this could cause unexpected and adverse results.
Visit your Sites & Organizations page.
Click on the site settings gear icon 
to visit your site settings page.
Expand the Session targeting & tracking menu.
Enter the top-level domain name you wish to allow under the heading ALLOWED IFRAME DOMAINS.
Only enter the top-level domain when entering domain names into the ALLOWED IFRAME DOMAINS field. The top-level domain 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