Don't have one? Create one ↗
The Happy TaggerThe Happy Tagger
← All courses

Lesson 2 of 3

Iframe PostMessage Bridge

① Connect your GTM container

Paste your container ID to load it into this page. It only ever runs here.

Advanced: use a specific environment

An iframe is a separate document. The widget inside it, a booking calendar, a chat box, a payment form, can't reach your page's dataLayer or GTM directly: browsers isolate cross-frame access for security. So a click inside the embed is invisible to your container.

The bridge is postMessage. The iframe posts a structured message to its parent; a small listener on your page receives it, validates the origin, and relays it into the dataLayer as a normal event. From there it's the usual loop: a Custom Event trigger and a tag.

The embedded widget below posts iframe_cta when its button is clicked. Build the relay listener and tag the event. In production, never skip the event.origin check.

Goal

Relay an iframe's event into the parent dataLayer with postMessage and fire a tag on it.

Build it in GTM

  1. Listener: Custom HTML - Iframe Bridge

    1. Go to Tags → New → Custom HTML.
    2. Add a message listener that validates the origin, then relays the event:
      <script>window.addEventListener('message',function(e){if(e.origin!=='https://widget.example.com')return;if(e.data&&e.data.type==='ht_iframe'){window.dataLayer.push({event:e.data.event,source:e.data.source});}});</script>
    3. Trigger it on All Pages, name it Custom HTML - Iframe Bridge and Save.

  2. Trigger: Custom Event - Iframe CTA

    Add a Custom Event trigger on iframe_cta, name it Custom Event - Iframe CTA and Save.

  3. Tag: a GA4 Event tag (or Custom HTML - Test)

    Add a tag firing on Custom Event - Iframe CTA, reading source as a parameter, then Save.

Debug in Tag Assistant

Copy this lesson's live URL and paste it into GTM Preview, that is the page Tag Assistant connects to. It has the clickable elements, so this page stays clean for reading.

  1. In your GTM, click Preview.
  2. Paste the live URL above and click Connect.
  3. Interact with the live page and watch your tag fire in Tag Assistant.

What you should expect to see

Clicking the button inside the iframe relays iframe_cta to the parent dataLayer and your tag fires, carrying source: embedded_widget.

Verify your container

Built it? Export your container, Admin → Export Container, choose your workspace, then drop the JSON here to check it against this lesson.

Drop your container .json here

or browse · checked in your browser, nothing is uploaded

0 of 3 lessons complete