Súhlas vo vnútri cross-origin iframov: Vzor __tcfapiLocator a __gppLocator
Problém: Súhlas žije v hornom okne
CMP beží na vašej stránke, v okne najvyššej úrovne. Veľká časť vašej reklamy nie. Display kreatívy, rich media, renderery header biddingu a mnohé widgety tretích strán bežia vo vnútri iframov, často na inom origine. Kód v cross-origin iframe nemôže priamo volať funkciu na nadradenej stránke, takže nemôže jednoducho zavolať __tcfapi alebo __gpp a prečítať voľbu návštevníka.
Rámce IAB to riešia malou, dobre definovanou konvenciou správ. Ak vytvárate reklamné produkty, embedy alebo meracie skripty, ktoré bežia v rámcoch, alebo ak ladíte reklamné stacky, ktoré to robia, oplatí sa vedieť presne, ako to funguje.
Locator rámec
Popri JavaScriptovom API pridáva CMP s TCF do stránky najvyššej úrovne prázdny, neviditeľný iframe s názvom __tcfapiLocator. CMP s GPP robí to isté s rámcom s názvom __gppLocator. Tieto rámce nenesú žiadny obsah. Ich jedinou úlohou je byť nájditeľné: ktorýkoľvek skript v ktoromkoľvek vnorenom rámci môže prejsť hierarchiou okien nahor a skontrolovať, či na každej úrovni existuje rámec s týmto názvom.
Keďže názvy rámcov sú viditeľné cez originy prostredníctvom window.frames, skript v hlboko vnorenom cross-origin iframe vie nájsť okno, ktoré hostí CMP, bez prístupu k čomukoľvek inému na tej stránke.
Ako skript v rámci nájde CMP
- Začnite s aktuálnym oknom. Ak __tcfapi existuje lokálne, použite ho priamo — skript nie je v rámci, alebo rámec zdieľa CMP.
- Inak cyklujte nahor: skontrolujte, či aktuálne okno obsahuje rámec s názvom __tcfapiLocator; ak nie, prejdite na window.parent a skontrolujte znova, pričom skončíte pri hornom okne.
- Keď sa locator nájde, okno, ktoré ho obsahuje, je oknom CMP. Komunikácia teraz prebieha cez postMessage.
Každý prístup zabaľte do try/catch, pretože niektoré prehliadače alebo nastavenia sandboxu vyhadzujú výnimku pri cross-origin prístupe k vlastnostiam, a cyklus zastavte, keď sa window.parent rovná aktuálnemu oknu.
Formát správy
Pri TCF skript v rámci pošle oknu CMP správu obsahujúcu objekt s vlastnosťou __tcfapiCall. Vo vnútri sú štyri polia:
- command — napríklad getTCData, ping alebo addEventListener;
- parameter — akýkoľvek argument, ktorý príkaz potrebuje, alebo null;
- version — verzia API, 2 pre TCF v2;
- callId — jedinečná hodnota generovaná volajúcim.
CMP tieto správy počúva, vykoná príkaz a pošle späť objekt s vlastnosťou __tcfapiReturn obsahujúcou returnValue, success a rovnaké callId. Volajúci si drží mapu čakajúcich callbackov podľa callId, počúva udalosti message a každú odpoveď doručí správnemu callbacku. GPP sleduje rovnaký vzor s __gppCall a __gppReturn.
Mnohé integrácie píšu malý proxy: lokálnu funkciu s názvom __tcfapi vo vnútri rámca, ktorá prekladá volania na správy. Kód napísaný pre horné okno potom funguje v rámci bez zmeny.
Event listenery naprieč rámcami
Volanie addEventListener poslané cez postMessage nie je jednorazová žiadosť. CMP pošle návratovú správu zakaždým, keď sa zmení stav súhlasu, všetky s rovnakým callId. Váš dispatcher preto musí tento callback ponechať zaregistrovaný, a nie ho po prvej odpovedi zmazať. Zabudnutie na to je klasická chyba: skript v rámci prečíta súhlas raz a neskoršie odvolanie nikdy nezaregistruje.
Bezpečnostné úvahy
- Overujte tvar správy. Ignorujte každú správu, ktorá neobsahuje očakávanú vlastnosť, a reťazcové payloady parsujte defenzívne, keďže niektoré implementácie posielajú reťazce JSON namiesto objektov.
- Neverte slepo. Ktorákoľvek stránka môže posielať správy do vášho rámca. Odpovede berte ako signály súhlasu, ktoré treba rešpektovať, nie ako autentifikované údaje, a nikdy nedovoľte, aby spúšťali privilegované akcie.
- Používajte konkrétne cieľové originy, kde môžete. Keď je origin CMP známy, posielajte správy jemu, nie všetkým originom.
Kam vzor nedosahuje
Niektoré reklamné prostredia izolujú kreatívy prísnejšie. Kontajnery SafeFrame, sandboxované iframy bez správnych oprávnení a kreatívy renderované v samostatných dokumentoch nemusia vedieť prechádzať strom rámcov ani prijímať správy. V takých prípadoch sa signál súhlasu zvyčajne musí odovzdať explicitne, napríklad ako parametre v žiadosti o reklamu alebo hodnoty odovzdané kreatíve ad serverom, ako sú parametre gdpr a gdpr_consent, ktoré podporuje mnoho reklamných tagov.
Kontrolný zoznam ladenia
- V DevTools horného okna overte na paneli Elements, že locator rámce existujú.
- Prepnite kontext konzoly na iframe a skontrolujte, či je odtiaľ locator dosiahnuteľný.
- Logujte prichádzajúce udalosti message v oboch oknách, aby ste potvrdili, že volania a odpovede prúdia.
- Zmeňte súhlas v banneri a overte, že listenery v rámcoch dostanú aktualizáciu.
- Testujte s neskoro načítaným CMP, aby ste sa uistili, že kód v rámci skúša znova alebo čaká, namiesto toho, aby to hneď vzdal.
Kľúčové poznatky
- Cross-origin rámce sa dostanú k CMP cez rámce __tcfapiLocator a __gppLocator.
- Volania a odpovede používajú postMessage s __tcfapiCall/__tcfapiReturn alebo ekvivalentmi GPP, párované podľa callId.
- Callbacky listenerov nechajte zaregistrované, aby neskoršie zmeny súhlasu prišli.
- Overujte každú správu a nepovažujte ju za dôveryhodný vstup.
- Tam, kde sú rámce plne izolované, odovzdajte súhlas explicitne v žiadosti o reklamu.