Consimțământul în iframe-uri cross-origin: modelul __tcfapiLocator și __gppLocator
Problema: consimțământul trăiește în fereastra de sus
Un CMP rulează pe pagina ta, în fereastra de nivel superior. O mare parte din publicitatea ta nu. Creativele display, rich media, randatoarele de header bidding și multe widgeturi terțe rulează în iframe-uri, adesea de pe altă origine. Codul dintr-un iframe cross-origin nu poate apela direct o funcție a paginii părinte, deci nu poate pur și simplu să apeleze __tcfapi sau __gpp și să citească alegerea vizitatorului.
Cadrele IAB rezolvă acest lucru cu o convenție de mesagerie mică și bine definită. Dacă dezvolți produse publicitare, încorporări sau scripturi de măsurare care rulează în cadre sau dacă depanezi stive publicitare care o fac, merită să știi exact cum funcționează.
Frame-ul locator
Pe lângă API-ul JavaScript, un CMP TCF adaugă pe pagina de nivel superior un iframe gol și invizibil numit __tcfapiLocator. Un CMP GPP face același lucru cu un frame numit __gppLocator. Cadrele nu au conținut. Singura lor sarcină este să poată fi găsite: orice script din orice cadru imbricat poate urca prin ierarhia ferestrelor și poate verifica dacă la fiecare nivel există un cadru cu acel nume.
Deoarece numele cadrelor sunt vizibile între origini prin window.frames, un script dintr-un iframe cross-origin imbricat adânc poate localiza fereastra care găzduiește CMP-ul fără a avea acces la nimic altceva de pe acea pagină.
Cum găsește un script din cadru CMP-ul
- Începe cu fereastra curentă. Dacă __tcfapi există local, folosește-l direct — scriptul nu este într-un cadru sau cadrul partajează CMP-ul.
- Altfel, urcă în buclă: verifică dacă fereastra curentă conține un cadru numit __tcfapiLocator; dacă nu, treci la window.parent și verifică din nou, oprindu-te la fereastra de sus.
- Când locatorul este găsit, fereastra care îl conține este fereastra CMP. Comunicarea se face de acum prin postMessage.
Învelește fiecare acces într-un try/catch, pentru că unele browsere sau setări de sandbox aruncă o eroare la accesarea proprietăților cross-origin, și oprește bucla atunci când window.parent este egal cu fereastra curentă.
Formatul mesajului
Pentru TCF, scriptul din cadru trimite un mesaj către fereastra CMP, conținând un obiect cu proprietatea __tcfapiCall. În interior sunt patru câmpuri:
- command — de exemplu getTCData, ping sau addEventListener;
- parameter — orice argument de care are nevoie comanda, sau null;
- version — versiunea API, 2 pentru TCF v2;
- callId — o valoare unică generată de apelant.
CMP-ul ascultă aceste mesaje, execută comanda și trimite înapoi un obiect cu proprietatea __tcfapiReturn, care conține returnValue, success și același callId. Apelantul păstrează o hartă a callback-urilor în așteptare, indexată după callId, ascultă evenimentele message și trimite fiecare răspuns la callback-ul potrivit. GPP urmează același tipar cu __gppCall și __gppReturn.
Multe integrări scriu un proxy mic: o funcție locală numită __tcfapi în interiorul cadrului, care traduce apelurile în mesaje. Astfel, codul scris pentru fereastra de sus funcționează neschimbat în cadru.
Listener-e de evenimente între cadre
Un apel addEventListener trimis prin postMessage nu este o cerere unică. CMP-ul va trimite un mesaj de răspuns de fiecare dată când se schimbă starea consimțământului, toate cu același callId. Dispecerul tău trebuie, prin urmare, să țină acel callback înregistrat, în loc să îl șteargă după primul răspuns. Uitarea acestui lucru este o eroare clasică: scriptul din cadru citește consimțământul o dată și nu observă niciodată o retragere ulterioară.
Considerații de securitate
- Validează forma mesajului. Ignoră orice mesaj care nu conține proprietatea așteptată și analizează cu prudență conținuturile de tip șir, deoarece unele implementări trimit șiruri JSON în loc de obiecte.
- Nu te încrede orbește. Orice pagină poate trimite mesaje către cadrul tău. Tratează răspunsurile ca semnale de consimțământ de respectat, nu ca date autentificate, și nu le lăsa niciodată să declanșeze acțiuni privilegiate.
- Folosește origini țintă specifice acolo unde poți. Când origina CMP-ului este cunoscută, trimite mesajul către ea, nu către toate originile.
Unde nu ajunge modelul
Unele medii publicitare izolează creativele mai strict. Containerele SafeFrame, iframe-urile în sandbox fără permisiunile potrivite și creativele randate în documente separate pot să nu poată parcurge arborele de cadre sau primi mesaje. În aceste cazuri, semnalul de consimțământ trebuie de obicei transmis explicit, de exemplu ca parametri ai cererii de anunț sau ca valori predate creativului de ad server, precum parametrii gdpr și gdpr_consent pe care îi acceptă multe taguri de anunțuri.
Listă de verificare pentru depanare
- În DevTools ale ferestrei de sus, confirmă că cadrele locator există în panoul Elements.
- Schimbă contextul consolei pe iframe și verifică dacă locatorul este accesibil de acolo.
- Înregistrează evenimentele message primite în ambele ferestre pentru a confirma că apelurile și răspunsurile circulă.
- Schimbă consimțământul în banner și verifică dacă listener-ele din cadre primesc o actualizare.
- Testează cu CMP-ul încărcat târziu, ca să te asiguri că codul din cadru reîncearcă sau așteaptă în loc să renunțe imediat.
Concluzii
- Cadrele cross-origin ajung la CMP prin cadrele __tcfapiLocator și __gppLocator.
- Apelurile și răspunsurile folosesc postMessage cu __tcfapiCall/__tcfapiReturn sau echivalentele GPP, asociate prin callId.
- Păstrează înregistrate callback-urile listener-elor, ca modificările ulterioare de consimțământ să ajungă.
- Validează fiecare mesaj și evită să îl tratezi ca intrare de încredere.
- Acolo unde cadrele sunt complet izolate, transmite consimțământul explicit în cererea de anunț.