How to track Forms embedded in iframes

Forms embedded in iframes can be tracked with Matomo Form Analytics by manually scanning the iframe document after it loads, using FormAnalytics::scanForForms.

This method works only when the parent page (page embedding the iframe) can access the iframe content. Many third-party iframes block access due to browser security restrictions and the iframe document cannot be scanned directly.

If the iframe provider supports window.postMessage(), it may be possible to track iframe interactions by sending events from the iframe to the parent page. When the third-party provider does not support iframe communication, consider tracking a thank-you page, redirect, callback, or custom JavaScript event instead.

Using Matomo Tag Manager? Read the guide on tracking iframe interactions using custom events.

Scan accessible iframe forms

If the iframe document is accessible from the page embedding the iframe, you can manually scan the iframe document using FormAnalytics::scanForForms.

1. Add the Matomo tracking code to the web page embedding the iframe.
2. In Matomo, go to Administration > Websites (or Measurables) > Tracking Code.
3. Copy your tracking code and paste it before the closing </head> tag on page that embeds the iframe.
4. Add the following scanForms script after the iframe element using your iframe id.
5. This script waits for the iframe to load, scans the iframe document for forms, and registers detected forms with Form Analytics. The additional load event handling helps when the iframe loads before the script executes.

//EXAMPLE IFRAME//
<iframe
 id="contact-form-iframe"
 src="https://example.com/form.html"
 style="width:100%; height:350px; border:1px solid #ccc;">
</iframe>

// ADD THE SCRIPT TO SCAN THE IFRAME//
var updatedElement = document.getElementById('contact-form-iframe');

if (updatedElement) {
    function scanForms() {
        _paq.push(['FormAnalytics::scanForForms', updatedElement.contentWindow.document]);
    }

    try {
        // Access the iframe's document to check if it's already loaded
        if (updatedElement.contentWindow.document.readyState === 'complete') {
            // The iframe is already loaded
            scanForms();
        } else {
            // The iframe is not loaded yet; add an event listener
            updatedElement.addEventListener('load', scanForms);
        }
    } catch (e) {
        // If accessing contentWindow.document throws an error due to cross-origin policy,
        // we fallback to adding the event listener
        updatedElement.addEventListener('load', scanForms);
    }
}

Configure Form Analytics

After adding the iframe scan script, configure the form in Form Analytics so Matomo knows which iframe form to track and when to record a conversion.

1. Add the form in Form Analytics.
2. Set the form conditions, for example, Form ID equals contactForm.
3. Set the conversion rule so the form is converted when: The form is submitted.
   

Test the iframe form tracking

After configuring the form, verify that Matomo can detect and track the iframe form.

1. Open the page containing the iframe form.
2. Go to your browser developer tools > Console and Network tabs.
3. Reload the page and confirm the iframe scan script executes successfully.
4. Interact with the iframe form and submit it.
5. In Matomo, go to the Real-time report and Visits Log to check your visit appears with the form conversion.
   
6. View reports under Forms in the Matomo reporting menu to confirm the form appears in the report with interactions or submissions.

If the form does not appear in the Forms report:

• verify the iframe ID used in the scan script matches the iframe on the page.
• ensure the form ID configured in Form Analytics matches the form inside the iframe.
• check for browser console errors related to iframe.contentWindow.document.
• confirm the iframe document is accessible from the parent page.

Example browser error for blocked cross-origin iframe access:

Blocked a frame with origin "https://example.com" from accessing a cross-origin frame.

This error indicates the iframe document cannot be scanned directly from the parent page.

Cross-origin iframe limitations

Some third-party iframes use browser cross-origin restrictions that block access to: iframe.contentWindow.document

When this occurs, the iframe document cannot be scanned from the page embedding the iframe. If you have access to edit both the iframe source and the parent page, you can instead communicate between the iframe and parent page using window.postMessage().

For example, the iframe can send a message when a form is submitted:

<script>
document.getElementById('contactForm').addEventListener('submit', function () {

    window.parent.postMessage({
        formSubmitted: true,
        formId: 'contactForm'
    }, 'https://example.com');

});
</script>

The parent page can then listen for the message and trigger Matomo tracking.