Privola unutar cross-origin iframeova: obrazac __tcfapiLocator i __gppLocator
Problem: privola živi u glavnom prozoru
CMP radi na vašoj stranici, u prozoru najviše razine. Velik dio vašeg oglašavanja ne radi. Display kreative, rich media, header bidding renderere i mnoge widgete trećih strana izvode se unutar iframeova, često na drugom originu. Kod u cross-origin iframeu ne može izravno pozvati funkciju na roditeljskoj stranici, pa ne može jednostavno pozvati __tcfapi ili __gpp i pročitati izbor posjetitelja.
IAB okviri to rješavaju malom, dobro definiranom konvencijom slanja poruka. Ako gradite oglasne proizvode, embedove ili skripte za mjerenje koje rade u okvirima, ili debugirate ad stackove koji to rade, vrijedi točno znati kako funkcionira.
Locator okvir
Uz JavaScript API, TCF CMP dodaje prazan, nevidljiv iframe pod imenom __tcfapiLocator na stranicu najviše razine. GPP CMP čini isto s okvirom pod imenom __gppLocator. Ovi okviri nemaju sadržaja. Jedini im je posao da budu pronalazivi: svaka skripta u bilo kojem ugniježđenom okviru može se penjati uz hijerarhiju prozora i na svakoj razini provjeriti postoji li okvir s tim imenom.
Budući da su imena okvira vidljiva između različitih origina kroz window.frames, skripta u duboko ugniježđenom cross-origin iframeu može locirati prozor koji hosta CMP, a da nema pristup ničemu drugom na toj stranici.
Kako skripta u okviru pronalazi CMP
- Počnite od trenutačnog prozora. Ako __tcfapi postoji lokalno, koristite ga izravno — skripta nije u okviru ili okvir dijeli CMP.
- U protivnom, krećite se prema gore u petlji: provjerite sadrži li trenutačni prozor okvir pod imenom __tcfapiLocator; ako ne, prijeđite na window.parent i ponovno provjerite, zaustavljajući se na najvišem prozoru.
- Kad se locator pronađe, prozor koji ga sadrži jest prozor CMP-a. Komunikacija se sada odvija putem postMessage.
Svaki pristup omotajte u try/catch, jer neki preglednici ili postavke sandboxa bacaju pogrešku pri cross-origin pristupu svojstvima, i zaustavite petlju kad window.parent bude jednak trenutačnom prozoru.
Format poruke
Za TCF, skripta u okviru šalje poruku prozoru CMP-a koja sadrži objekt sa svojstvom __tcfapiCall. Unutar njega su četiri polja:
- command — na primjer getTCData, ping ili addEventListener;
- parameter — svaki argument koji naredba traži, ili null;
- version — verzija API-ja, 2 za TCF v2;
- callId — jedinstvena vrijednost koju generira pozivatelj.
CMP sluša ove poruke, izvršava naredbu i šalje natrag objekt sa svojstvom __tcfapiReturn koji sadrži returnValue, success i isti callId. Pozivatelj drži mapu callbackova na čekanju po ključu callId, sluša message događaje i svaki odgovor usmjerava na pravi callback. GPP slijedi isti obrazac s __gppCall i __gppReturn.
Mnoge integracije pišu mali proxy: lokalnu funkciju pod imenom __tcfapi unutar okvira koja pozive prevodi u poruke. Kod pisan za glavni prozor tada radi nepromijenjen unutar okvira.
Event listeneri preko okvira
Poziv addEventListener poslan putem postMessage nije jednokratan zahtjev. CMP će poslati povratnu poruku svaki put kad se stanje privole promijeni, sve s istim callId. Vaš dispatcher stoga mora zadržati taj callback registriran umjesto da ga obriše nakon prvog odgovora. Zaboraviti to klasična je greška: skripta u okviru jednom pročita privolu i nikad ne primijeti kasniji opoziv.
Sigurnosna razmatranja
- Provjeravajte oblik poruke. Ignorirajte svaku poruku koja ne sadrži očekivano svojstvo i oprezno parsirajte string payloade, jer neke implementacije šalju JSON stringove umjesto objekata.
- Ne vjerujte slijepo. Svaka stranica može slati poruke vašem okviru. Odgovore tretirajte kao signale privole koje treba poštovati, a ne kao autentificirane podatke, i nikad ne dopustite da pokreću privilegirane radnje.
- Koristite specifične ciljne origine gdje možete. Kad je origin CMP-a poznat, šaljite poruku njemu, a ne svim originima.
Dokle obrazac ne seže
Neka oglasna okruženja strože izoliraju kreative. SafeFrame spremnici, sandboxirani iframeovi bez odgovarajućih dopuštenja i kreative renderirane u zasebnim dokumentima možda ne mogu proći kroz stablo okvira niti primati poruke. U tim slučajevima signal privole obično se mora proslijediti eksplicitno, na primjer kao parametri na oglasnom zahtjevu ili vrijednosti koje ad server predaje kreativi, kao što su parametri gdpr i gdpr_consent koje podržavaju mnogi ad tagovi.
Kontrolni popis za debugiranje
- U DevToolsu glavnog prozora potvrdite da locator okviri postoje u panelu Elements.
- Prebacite kontekst konzole na iframe i provjerite je li locator odande dostupan.
- Logirajte dolazne message događaje u oba prozora da potvrdite da pozivi i odgovori teku.
- Promijenite privolu u baneru i provjerite da listeneri u okvirima dobivaju ažuriranje.
- Testirajte s kasno učitanim CMP-om, da se uvjerite da kod u okviru pokušava ponovno ili čeka, a ne odustaje odmah.
Ključni zaključci
- Cross-origin okviri dolaze do CMP-a preko okvira __tcfapiLocator i __gppLocator.
- Pozivi i odgovori koriste postMessage s __tcfapiCall/__tcfapiReturn ili GPP ekvivalentima, upareni preko callId.
- Držite callbackove listenera registriranima da kasnije promjene privole stižu.
- Provjerite svaku poruku i nemojte je tretirati kao pouzdan ulaz.
- Gdje su okviri potpuno izolirani, proslijedite privolu eksplicitno na oglasnom zahtjevu.