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
- 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.
- 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.
- 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:
- command — for example getTCData, ping or addEventListener;
- parameter — any argument the command needs, or null;
- version — the API version, 2 for TCF v2;
- callId — a unique value generated by the caller.
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
- Validate message shape. Ignore any message that does not contain the expected property, and parse string payloads defensively, since some implementations send JSON strings rather than objects.
- Do not trust blindly. Any page can post messages to your frame. Treat responses as consent signals to honour, not as authenticated data, and never let them trigger privileged actions.
- Use specific target origins where you can. When the CMP origin is known, post to it rather than to every origin.
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
- In the top window’s DevTools, confirm the locator frames exist in the Elements panel.
- Switch the console context to the iframe and check whether the locator is reachable from there.
- Log incoming message events in both windows to confirm calls and returns are flowing.
- Change consent in the banner and verify that framed listeners receive an update.
- Test with the CMP loaded late, to make sure framed code retries or waits rather than giving up immediately.
Key Takeaways
- Cross-origin frames reach the CMP through the __tcfapiLocator and __gppLocator frames.
- Calls and returns use postMessage with __tcfapiCall/__tcfapiReturn or the GPP equivalents, matched by callId.
- Keep listener callbacks registered so later consent changes arrive.
- Validate every message and avoid treating it as trusted input.
- Where frames are fully isolated, pass consent explicitly on the ad request.