Souhlas uvnitř cross-origin iframů: vzor __tcfapiLocator a __gppLocator
Problém: souhlas žije v hlavním okně
CMP běží na vaší stránce, v okně nejvyšší úrovně. Velká část vaší reklamy ne. Display kreativy, rich media, renderery header biddingu a mnoho widgetů třetích stran běží uvnitř iframů, často na jiném originu. Kód v cross-origin iframu nemůže přímo volat funkci na nadřazené stránce, takže jednoduše nemůže zavolat __tcfapi nebo __gpp a přečíst volbu návštěvníka.
Rámce IAB to řeší malou, dobře definovanou konvencí zasílání zpráv. Pokud vyvíjíte reklamní produkty, embedy nebo měřicí skripty, které běží v rámcích, nebo ladíte reklamní stacky, které to dělají, vyplatí se přesně vědět, jak to funguje.
Locator rámec
Vedle JavaScript API přidává CMP s TCF na stránku nejvyšší úrovně prázdný, neviditelný iframe pojmenovaný __tcfapiLocator. CMP s GPP dělá totéž s rámcem pojmenovaným __gppLocator. Tyto rámce nemají žádný obsah. Jejich jediným úkolem je být nalezitelné: jakýkoli skript v libovolném vnořeném rámci může procházet hierarchii oken nahoru a na každé úrovni zkontrolovat, zda rámec s tímto názvem existuje.
Protože jsou názvy rámců viditelné napříč originy přes window.frames, může skript v hluboce vnořeném cross-origin iframu najít okno, které CMP hostuje, aniž by měl přístup k čemukoli dalšímu na dané stránce.
Jak skript v rámci najde CMP
- Začněte aktuálním oknem. Pokud __tcfapi existuje lokálně, použijte ho přímo — skript není v rámci, nebo rámec sdílí CMP.
- Jinak se ve smyčce posouvejte nahoru: zkontrolujte, zda aktuální okno obsahuje rámec pojmenovaný __tcfapiLocator; pokud ne, přejděte na window.parent a zkontrolujte znovu, a zastavte se u nejvyššího okna.
- Když se locator najde, okno, které ho obsahuje, je okno CMP. Komunikace nyní probíhá přes postMessage.
Každý přístup obalte try/catch, protože některé prohlížeče nebo nastavení sandboxu při cross-origin přístupu k vlastnostem vyhazují chybu, a smyčku zastavte, když se window.parent rovná aktuálnímu oknu.
Formát zprávy
U TCF skript v rámci odešle oknu CMP zprávu obsahující objekt s vlastností __tcfapiCall. Uvnitř jsou čtyři pole:
- command — například getTCData, ping nebo addEventListener;
- parameter — jakýkoli argument, který příkaz potřebuje, nebo null;
- version — verze API, 2 pro TCF v2;
- callId — jedinečná hodnota generovaná volajícím.
CMP tyto zprávy poslouchá, provede příkaz a odešle zpět objekt s vlastností __tcfapiReturn obsahující returnValue, success a stejné callId. Volající si drží mapu čekajících callbacků podle klíče callId, poslouchá události message a každý návrat předá správnému callbacku. GPP se řídí stejným vzorem s __gppCall a __gppReturn.
Mnoho integrací píše malý proxy: lokální funkci pojmenovanou __tcfapi uvnitř rámce, která převádí volání na zprávy. Kód napsaný pro hlavní okno pak funguje beze změny i uvnitř rámce.
Event listenery napříč rámci
Volání addEventListener odeslané přes postMessage není jednorázový požadavek. CMP odešle zpětnou zprávu při každé změně stavu souhlasu, vždy se stejným callId. Váš dispatcher proto musí tento callback ponechat zaregistrovaný, místo aby ho po první odpovědi smazal. Zapomenout na to je klasická chyba: skript v rámci přečte souhlas jednou a pozdější odvolání nikdy nezaznamená.
Bezpečnostní úvahy
- Ověřujte tvar zprávy. Ignorujte každou zprávu, která neobsahuje očekávanou vlastnost, a řetězcové payloady parsujte obranně, protože některé implementace posílají JSON řetězce místo objektů.
- Nevěřte slepě. Libovolná stránka může vašemu rámci posílat zprávy. Odpovědi berte jako signály souhlasu, které je třeba respektovat, ne jako ověřená data, a nikdy je nenechte spouštět privilegované akce.
- Kde to jde, používejte konkrétní cílové originy. Pokud je origin CMP znám, posílejte zprávu jemu, ne všem originům.
Kam vzor nedosáhne
Některá reklamní prostředí kreativy izolují přísněji. Kontejnery SafeFrame, sandboxované iframy bez správných oprávnění a kreativy vykreslené v samostatných dokumentech nemusí být schopné procházet strom rámců ani přijímat zprávy. V takových případech je třeba signál souhlasu obvykle předat výslovně, například jako parametry reklamního požadavku nebo hodnoty, které ad server předá kreativě, jako jsou parametry gdpr a gdpr_consent, které podporuje mnoho reklamních tagů.
Checklist pro ladění
- V DevTools hlavního okna ověřte, že locator rámce existují na panelu Elements.
- Přepněte kontext konzole na iframe a zkontrolujte, zda je odtud locator dosažitelný.
- V obou oknech logujte příchozí události message, abyste ověřili, že volání a návraty proudí.
- Změňte souhlas v banneru a ověřte, že listenery v rámcích dostanou aktualizaci.
- Otestujte s pozdě načteným CMP, abyste si ověřili, že kód v rámci to zkouší znovu nebo čeká, a nevzdá to hned.
Klíčové poznatky
- Cross-origin rámce se k CMP dostanou přes rámce __tcfapiLocator a __gppLocator.
- Volání a návraty používají postMessage s __tcfapiCall/__tcfapiReturn nebo ekvivalenty GPP, spárované přes callId.
- Callbacky listenerů ponechte zaregistrované, aby docházely pozdější změny souhlasu.
- Ověřujte každou zprávu a neberte ji jako důvěryhodný vstup.
- Tam, kde jsou rámce zcela izolované, předejte souhlas výslovně v reklamním požadavku.