Cross-origin iframe-лердегі келісім: __tcfapiLocator және __gppLocator үлгісі
Мәселе: келісім жоғарғы терезеде тұрады
CMP бетіңізде, ең жоғарғы деңгейдегі терезеде жұмыс істейді. Жарнамаңыздың көп бөлігі олай емес. Дисплей креативтері, rich media, header bidding рендерлері және көптеген үшінші тарап виджеттері iframe-дердің ішінде, көбіне басқа origin-де жұмыс істейді. Cross-origin iframe-дегі код жоғарғы беттегі функцияны тікелей шақыра алмайды, сондықтан ол жай ғана __tcfapi немесе __gpp-ді шақырып, келушінің таңдауын оқи алмайды.
IAB фреймворктері мұны шағын, нақты анықталған хабар алмасу шартымен шешеді. Frame-дерде жұмыс істейтін жарнама өнімдерін, embed-терді немесе өлшеу скрипттерін жасасаңыз, немесе оларды қолданатын жарнама стектерін жөндесеңіз, оның дәл қалай жұмыс істейтінін білу пайдалы.
Locator frame
JavaScript API-мен қатар, TCF CMP жоғарғы деңгейдегі бетке __tcfapiLocator деп аталатын бос, көрінбейтін iframe қосады. GPP CMP дәл осыны __gppLocator деп аталатын frame-мен жасайды. Бұл frame-дерде контент жоқ. Олардың жалғыз міндеті — табылатын болу: кез келген ішкі орналасқан frame-дегі кез келген скрипт терезе иерархиясымен жоғары көтеріліп, әр деңгейде осындай атаулы frame бар-жоғын тексере алады.
Frame атаулары window.frames арқылы origin-дер арасында көрінетіндіктен, терең ішкі орналасқан cross-origin iframe-дегі скрипт сол беттегі басқа ештеңеге қолжетімділігі болмай-ақ CMP орналасқан терезені таба алады.
Frame ішіндегі скрипт CMP-ді қалай табады
- Ағымдағы терезеден бастаңыз. __tcfapi локалды бар болса, оны тікелей қолданыңыз — скрипт frame ішінде емес немесе frame CMP-ді бөліседі.
- Әйтпесе, жоғары қарай циклмен жүріңіз: ағымдағы терезеде __tcfapiLocator деп аталатын frame бар-жоғын тексеріңіз; жоқ болса, window.parent-ке өтіп, қайта тексеріңіз, жоғарғы терезеде тоқтаңыз.
- Locator табылғанда, оны қамтитын терезе — CMP терезесі. Байланыс енді postMessage арқылы жүреді.
Әр қатынауды try/catch ішіне орап қойыңыз, өйткені кейбір браузерлер немесе sandbox параметрлері cross-origin қасиетке қатынауда қате береді, ал window.parent ағымдағы терезеге тең болғанда циклді тоқтатыңыз.
Хабар форматы
TCF үшін frame ішіндегі скрипт CMP терезесіне __tcfapiCall қасиеті бар объектіні қамтитын хабар жібереді. Оның ішінде төрт өріс бар:
- command — мысалы, getTCData, ping немесе addEventListener;
- parameter — пәрмен қажет ететін кез келген аргумент немесе null;
- version — API нұсқасы, TCF v2 үшін 2;
- callId — шақырушы жасаған бірегей мән.
CMP бұл хабарларды тыңдайды, пәрменді орындайды және returnValue, success және сол callId бар __tcfapiReturn қасиетті объектіні кері жібереді. Шақырушы күтіп тұрған callback-тердің callId кілтті картасын сақтайды, message оқиғаларын тыңдайды және әр қайтарымды дұрыс callback-ке жеткізеді. GPP дәл осы үлгіні __gppCall және __gppReturn арқылы қолданады.
Көптеген интеграциялар шағын proxy жазады: frame ішінде шақыруларды хабарларға айналдыратын __tcfapi деп аталатын локалды функция. Сонда жоғарғы терезеге арнап жазылған код frame ішінде өзгеріссіз жұмыс істейді.
Frame-дер арасындағы оқиға тыңдаушылары
postMessage арқылы жіберілген addEventListener шақыруы бір реттік сұрау емес. CMP келісім күйі өзгерген сайын, барлығы бірдей callId-мен қайтарым хабарын жібереді. Сондықтан диспетчеріңіз бұл callback-ті бірінші жауаптан кейін жоймай, тіркеулі ұстауы керек. Мұны ұмыту — классикалық қате: frame ішіндегі скрипт келісімді бір рет оқиды және кейінгі кері қайтаруды ешқашан байқамайды.
Қауіпсіздік мәселелері
- Хабар пішінін тексеріңіз. Күтілетін қасиеті жоқ кез келген хабарды елемеңіз және жол жүктемелерін сақтықпен талдаңыз, өйткені кейбір іске асырулар объектінің орнына JSON жолдарын жібереді.
- Соқыр сенбеңіз. Кез келген бет frame-іңізге хабар жібере алады. Жауаптарды аутентификацияланған деректер емес, сақталуы тиіс келісім сигналдары ретінде қарастырыңыз және олардың артықшылықты әрекеттерді іске қосуына ешқашан жол бермеңіз.
- Мүмкіндігінше нақты target origin қолданыңыз. CMP origin-і белгілі болса, барлық origin-ге емес, оған жіберіңіз.
Үлгі жетпейтін жерлер
Кейбір жарнама орталары креативтерді қатаңырақ оқшаулайды. SafeFrame контейнерлері, қажетті рұқсаттарсыз sandbox-талған iframe-дер және бөлек құжаттарда рендерленген креативтер frame ағашымен жүре алмауы немесе хабар ала алмауы мүмкін. Мұндай жағдайларда келісім сигналы әдетте нақты берілуі керек, мысалы, жарнама сұрауындағы параметрлер немесе көптеген жарнама тегтері қолдайтын gdpr және gdpr_consent параметрлері сияқты жарнама сервері креативке беретін мәндер ретінде.
Жөндеу чек-парағы
- Жоғарғы терезенің DevTools-ында Elements панелінде locator frame-дерінің бар екенін растаңыз.
- Консоль контекстін iframe-ге ауыстырып, locator-ға сол жерден қол жеткізуге бола ма, соны тексеріңіз.
- Шақырулар мен қайтарымдар ағып жатқанын растау үшін екі терезеде де кіріс message оқиғаларын журналға жазыңыз.
- Баннерде келісімді өзгертіп, frame ішіндегі тыңдаушылар жаңартуды алатынын растаңыз.
- Frame ішіндегі код бірден берілмей, қайта әрекеттенетініне немесе күтетініне көз жеткізу үшін CMP кеш жүктелгенде сынаңыз.
Негізгі тұжырымдар
- Cross-origin frame-дер CMP-ге __tcfapiLocator және __gppLocator frame-дері арқылы жетеді.
- Шақырулар мен қайтарымдар callId арқылы сәйкестендірілетін __tcfapiCall/__tcfapiReturn немесе олардың GPP баламаларымен postMessage қолданады.
- Кейінгі келісім өзгерістері жетуі үшін тыңдаушы callback-терді тіркеулі ұстаңыз.
- Әр хабарды тексеріп, оны сенімді енгізу деп санаудан аулақ болыңыз.
- Frame-дер толық оқшауланған жерде келісімді жарнама сұрауында нақты жіберіңіз.