By default, Contentsquare will block iframe elements that are included in session data and prevent them from rendering content. Instead of the iframe content, while watching a session replay or viewing a heatmap, you'll see a message stating that we cannot track iframes embedded on your page.
This article provides guidance on tracking iframe content with Contentsquare, outlining different options to capture interactions depending on where the Contentsquare tag is installed. It also details the required steps and HTML attributes for enabling iframes, along with considerations and restrictions related to iframe behavior and third-party content.
What is an iframe?
An iframe is a web page embedded within another web page. It's commonly used to display content from third-party sites, like chatbots, videos, or forms, but can also show content from the same domain.
To determine where an iframe's content is coming from, we can look at the iframe source URL (src=""). In this example, the iframe source URL is coming from YouTube:
<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>
You can learn more about iframes in the Mozilla Developer Network documentation.
To fully understand this article, familiarise yourself with 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.
- 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.
What are my options to track iframe content with Contentsquare?
Contentsquare can only track sessions on pages with the Contentsquare tag installed. To track interactions in an iframe, you must be able to edit the iframe's source code. This may not be possible for third-party iframes. If the third party lets you add the Contentsquare tag, they must also consider Contentsquare tracking in their privacy and cookie policies.
Contentsquare can be used to track iframe content in the following ways:
- Install the Contentsquare tag only on the iframe parent page: Contentsquare will track the page content of the parent page, but no interactions will be tracked inside the iframe.
- Install the Contentsquare tag only on the iframe source page: Contentsquare will track the iframe's source page content, but interactions on the parent page won't be tracked. In session replays and heatmaps, you'll see the visited parent page, but only data from interactions within the iframe will be captured. Any user interactions with the parent page outside the iframe will not be captured.
- Install the same Contentsquare tag on both the iframe parent & source pages: Contentsquare can detect data from both the parent page and the iframe source page. The iframe content is treated as a separate page in Session Replay. Interactions with the iframe appear as another tab in the user's session, making it look like the user is switching between the parent and iframe source pages rather than viewing them simultaneously.
How to allow an iframe within Contentsquare
Allowing iframes to appear means Contentsquare can only load the iframe page, but can't track user interactions within the iframes unless you have the ability to add the Contentsquare tag 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 session replay and heatmaps.
Before you begin
Before allowing an iframe, consider the limitations that will persist even after allowing the iframe:
- The iframe must have a src attribute.
- Contentsquare cannot allow an iframe if its src attribute uses a relative page path (Example: src=“/page”) instead of the complete URL (Example: src=“https://contentsquare.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 capturing the parent page.
- The URL that the iframe points to is stored on our servers and reloaded every time a session replay is played. This means that if loading the iframe source page triggers some additional behavior, this could cause unexpected and adverse results.
- Allowing an iframe means adding an attribute to the <iframe> element itself. It 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.
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 Contentsquare 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.
Allowing an iframe within Contentsquare
1. 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.
2. Visit your Sites & Organizations page.
3. Click on the site settings gear icon to visit your site settings page.
4. Expand the Session targeting & tracking menu.
5. 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.contentsquare.com/ to this field, the top-level domain would be contentsquare.com
6. Click Save Changes.