Consent sa Loob ng mga Cross-Origin Iframe: Ang __tcfapiLocator at __gppLocator na Pattern
Ang Problema: Nasa Top Window ang Consent
Tumatakbo ang CMP sa iyong page, sa top-level window. Hindi gayon ang karamihan sa iyong advertising. Ang mga display creative, rich media, header bidding renderer at maraming third-party widget ay tumatakbo sa loob ng mga iframe, madalas sa ibang origin. Hindi direktang matatawag ng code sa cross-origin iframe ang function sa parent page, kaya hindi nito basta matatawag ang __tcfapi o __gpp para basahin ang pagpili ng bisita.
Nilulutas ito ng mga framework ng IAB gamit ang maliit at maayos na tinukoy na messaging convention. Kung gumagawa ka ng mga ad product, embed o measurement script na tumatakbo sa mga frame, o nagde-debug ng mga ad stack na gumagawa nito, mainam na alam mo nang eksakto kung paano ito gumagana.
Ang Locator Frame
Bukod sa JavaScript API, nagdaragdag ang TCF CMP ng walang laman at di-nakikitang iframe na pinangalanang __tcfapiLocator sa top-level page. Ganoon din ang ginagawa ng GPP CMP sa frame na pinangalanang __gppLocator. Walang dalang content ang mga frame. Ang tanging trabaho nila ay mahanap: ang anumang script sa anumang nested na frame ay maaaring umakyat sa window hierarchy at suriin kung may frame na may ganoong pangalan sa bawat antas.
Dahil nakikita sa iba't ibang origin ang mga pangalan ng frame sa pamamagitan ng window.frames, matutukoy ng script sa malalim na nested na cross-origin iframe ang window na nagho-host ng CMP nang hindi nakaaabot sa anupamang bagay sa page na iyon.
Paano Nahahanap ng Framed Script ang CMP
- Magsimula sa kasalukuyang window. Kung lokal na umiiral ang __tcfapi, gamitin ito nang direkta — wala sa frame ang script, o ibinabahagi ng frame ang CMP.
- Kung hindi, mag-loop paitaas: suriin kung may frame na pinangalanang __tcfapiLocator ang kasalukuyang window; kung wala, lumipat sa window.parent at suriin muli, na humihinto sa top window.
- Kapag nahanap ang locator, ang window na naglalaman nito ang window ng CMP. Sa postMessage na nagaganap ang komunikasyon.
Balutin ng try/catch ang bawat access, dahil nagtatapon ng error ang ilang browser o sandboxing setting sa cross-origin na property access, at ihinto ang loop kapag ang window.parent ay katumbas ng kasalukuyang window.
Ang Format ng Mensahe
Para sa TCF, nagpo-post ang framed script ng mensahe sa CMP window na naglalaman ng object na may property na __tcfapiCall. Sa loob nito ay apat na field:
- command — halimbawa getTCData, ping o addEventListener;
- parameter — anumang argumentong kailangan ng command, o null;
- version — ang bersyon ng API, 2 para sa TCF v2;
- callId — natatanging halagang binuo ng caller.
Nakikinig ang CMP sa mga mensaheng ito, pinapatakbo ang command, at nagpo-post pabalik ng object na may property na __tcfapiReturn na naglalaman ng returnValue, success at parehong callId. Nagtatabi ang caller ng map ng mga nakabinbing callback na naka-key sa callId, nakikinig sa mga message event, at ipinapadala ang bawat return sa tamang callback. Sumusunod ang GPP sa parehong pattern gamit ang __gppCall at __gppReturn.
Maraming integrasyon ang sumusulat ng maliit na proxy: isang lokal na function na pinangalanang __tcfapi sa loob ng frame na nagsasalin ng mga tawag tungo sa mga mensahe. Gumagana nang walang pagbabago sa loob ng frame ang code na isinulat para sa top window.
Mga Event Listener sa Iba't ibang Frame
Hindi minsanang request ang addEventListener na ipinadala sa pamamagitan ng postMessage. Magpo-post ang CMP ng return message sa tuwing nagbabago ang consent state, lahat ay may parehong callId. Kaya kailangang panatilihing nakarehistro ng iyong dispatcher ang callback na iyon sa halip na burahin ito pagkatapos ng unang response. Klasikong bug ang makalimutan ito: minsan lang nababasa ng framed script ang consent at hindi nito napapansin ang kasunod na withdrawal.
Mga Konsiderasyon sa Seguridad
- I-validate ang hugis ng mensahe. Huwag pansinin ang anumang mensaheng walang inaasahang property, at i-parse nang may pag-iingat ang mga string payload, dahil may mga implementasyong nagpapadala ng JSON string sa halip na object.
- Huwag basta magtiwala. Maaaring mag-post ng mensahe sa iyong frame ang anumang page. Ituring ang mga response bilang consent signal na dapat igalang, hindi bilang authenticated na data, at huwag hayaang mag-trigger ang mga ito ng privileged na aksyon.
- Gumamit ng tiyak na target origin kung maaari. Kapag alam ang origin ng CMP, doon mag-post sa halip na sa bawat origin.
Kung Saan Hindi Umaabot ang Pattern
Mas mahigpit na iniisolate ng ilang ad environment ang mga creative. Ang mga SafeFrame container, sandboxed iframe na walang tamang permiso, at mga creative na nire-render sa hiwalay na dokumento ay maaaring hindi makaakyat sa frame tree o makatanggap ng mensahe. Sa mga kasong iyon, karaniwang kailangang ipasa nang tahasan ang consent signal, halimbawa bilang mga parameter sa ad request o mga halagang ibinibigay ng ad server sa creative, gaya ng mga parameter na gdpr at gdpr_consent na sinusuportahan ng maraming ad tag.
Debugging Checklist
- Sa DevTools ng top window, tiyaking umiiral ang mga locator frame sa Elements panel.
- Ilipat ang console context sa iframe at suriin kung maaabot ang locator mula roon.
- I-log ang mga papasok na message event sa parehong window para kumpirmahing dumadaloy ang mga tawag at return.
- Baguhin ang consent sa banner at i-verify na nakatatanggap ng update ang mga framed listener.
- Subukan na huli ang pag-load ng CMP, para matiyak na nagre-retry o naghihintay ang framed code at hindi agad sumusuko.
Mga Pangunahing Takeaway
- Naaabot ng mga cross-origin frame ang CMP sa pamamagitan ng mga frame na __tcfapiLocator at __gppLocator.
- Gumagamit ng postMessage ang mga tawag at return na may __tcfapiCall/__tcfapiReturn o katumbas na GPP, na pinagtutugma ng callId.
- Panatilihing nakarehistro ang mga listener callback para makarating ang mga susunod na pagbabago sa consent.
- I-validate ang bawat mensahe at huwag ituring na pinagkakatiwalaang input.
- Kung saan ganap na naka-isolate ang mga frame, ipasa nang tahasan ang consent sa ad request.