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

  1. 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.
  2. 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.
  3. 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:

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

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í

Klíčové poznatky

← Blog Číst vše →