Consent Inside Cross-Origin Iframes: The __tcfapiLocator and __gppLocator Pattern

The Problem: Consent Lives in the Top Window

A CMP runs on your page, in the top-level window. Much of your advertising does not. Display creatives, rich media, header bidding renderers and many third-party widgets run inside iframes, often on a different origin. Code in a cross-origin iframe cannot call a function on the parent page directly, so it cannot simply call __tcfapi or __gpp and read the visitor’s choice.

The IAB frameworks solve this with a small, well-defined messaging convention. If you build ad products, embeds or measurement scripts that run in frames, or if you debug ad stacks that do, it is worth knowing exactly how it works.

The Locator Frame

Alongside the JavaScript API, a TCF CMP adds an empty, invisible iframe named __tcfapiLocator to the top-level page. A GPP CMP does the same with a frame named __gppLocator. The frames carry no content. Their only job is to be findable: any script in any nested frame can walk up the window hierarchy and check whether a frame with that name exists at each level.

Because frame names are visible across origins through window.frames, a script in a deeply nested cross-origin iframe can locate the window that hosts the CMP without having access to anything else on that page.

How a Framed Script Finds the CMP

  1. Start with the current window. If __tcfapi exists locally, use it directly — the script is not in a frame, or the frame shares the CMP.
  2. Otherwise, loop upwards: check whether the current window contains a frame named __tcfapiLocator; if not, move to window.parent and check again, stopping at the top window.
  3. When the locator is found, the window containing it is the CMP’s window. Communication now happens through postMessage.

Wrap each access in a try/catch, because some browsers or sandboxing settings throw on cross-origin property access, and stop the loop when window.parent equals the current window.

The Message Format

For TCF, the framed script posts a message to the CMP window containing an object with a __tcfapiCall property. Inside it are four fields:

The CMP listens for these messages, runs the command, and posts back an object with a __tcfapiReturn property containing returnValue, success and the same callId. The caller keeps a map of pending callbacks keyed by callId, listens for message events, and dispatches each return to the right callback. GPP follows the same pattern with __gppCall and __gppReturn.

Many integrations write a small proxy: a local function named __tcfapi inside the frame that translates calls into messages. Code written for the top window then works unchanged inside the frame.

Event Listeners Across Frames

An addEventListener call sent through postMessage is not a one-off request. The CMP will post a return message every time the consent state changes, all with the same callId. Your dispatcher must therefore keep that callback registered rather than deleting it after the first response. Forgetting this is a classic bug: the framed script reads consent once and never notices a later withdrawal.

Security Considerations

Where the Pattern Does Not Reach

Some ad environments isolate creatives more strictly. SafeFrame containers, sandboxed iframes without the right permissions, and creatives rendered in separate documents may be unable to walk the frame tree or receive messages. In those cases, the consent signal usually has to be passed in explicitly, for example as parameters on the ad request or values handed to the creative by the ad server, such as the gdpr and gdpr_consent parameters many ad tags support.

Debugging Checklist

Key Takeaways

← Blog Read All →