Згода ўнутры крос-даменных iframe: патэрн __tcfapiLocator і __gppLocator
Праблема: згода жыве ў верхнім акне
CMP працуе на вашай старонцы, у акне верхняга ўзроўню. Значная частка вашай рэкламы — не. Медыйныя крэатывы, rich media, рэндэры header bidding і многія староннія віджэты працуюць унутры iframe, часта на іншай крыніцы. Код у крос-даменным iframe не можа наўпрост выклікаць функцыю бацькоўскай старонкі, таму ён не можа проста выклікаць __tcfapi або __gpp і прачытаць выбар наведвальніка.
Фрэймворкі IAB вырашаюць гэта невялікім, дакладна вызначаным пагадненнем аб абмене паведамленнямі. Калі вы ствараеце рэкламныя прадукты, убудоўваемыя блокі або скрыпты вымярэнняў, што працуюць у фрэймах, або адладжваеце рэкламныя стэкі, якія гэта робяць, варта ведаць, як менавіта гэта ўладкавана.
Фрэйм-лакатар
Побач з JavaScript API CMP паводле TCF дадае на старонку верхняга ўзроўню пусты нябачны iframe з назвай __tcfapiLocator. CMP паводле GPP робіць тое самае з фрэймам з назвай __gppLocator. У гэтых фрэймах няма змесціва. Іх адзіная задача — быць знойдзенымі: любы скрыпт у любым укладзеным фрэйме можа падымацца па іерархіі вокнаў і правяраць, ці існуе на кожным узроўні фрэйм з такой назвай.
Паколькі назвы фрэймаў бачныя паміж крыніцамі праз window.frames, скрыпт у глыбока ўкладзеным крос-даменным iframe можа знайсці акно, у якім размешчана CMP, не атрымліваючы доступу ні да чаго іншага на гэтай старонцы.
Як скрыпт у фрэйме знаходзіць CMP
- Пачніце з бягучага акна. Калі __tcfapi існуе лакальна, выкарыстоўвайце яе наўпрост — скрыпт не ў фрэйме, або фрэйм выкарыстоўвае тую ж CMP.
- Інакш падымайцеся ўверх у цыкле: праверце, ці змяшчае бягучае акно фрэйм з назвай __tcfapiLocator; калі не, перайдзіце да window.parent і праверце зноў, спыніўшыся на верхнім акне.
- Калі лакатар знойдзены, акно, якое яго змяшчае, і ёсць акно CMP. Далей зносіны ідуць праз postMessage.
Абгортвайце кожнае звяртанне ў try/catch, бо некаторыя браўзеры або налады пясочніцы выкідваюць выключэнне пры крос-даменным доступе да ўласцівасцей, і спыняйце цыкл, калі window.parent супадае з бягучым акном.
Фармат паведамленняў
Для TCF скрыпт у фрэйме адпраўляе акну CMP паведамленне, што змяшчае аб’ект з уласцівасцю __tcfapiCall. Унутры яго чатыры палі:
- command — напрыклад getTCData, ping або addEventListener;
- parameter — любы аргумент, патрэбны камандзе, або null;
- version — версія API, 2 для TCF v2;
- callId — унікальнае значэнне, згенераванае бокам, што выклікае.
CMP слухае гэтыя паведамленні, выконвае каманду і адпраўляе назад аб’ект з уласцівасцю __tcfapiReturn, які змяшчае returnValue, success і той самы callId. Бок, што выклікае, захоўвае табліцу чакаемых callback, ключом якой служыць callId, слухае падзеі message і перадае кожны адказ патрэбнаму callback. GPP прытрымліваецца таго ж шаблону з __gppCall і __gppReturn.
Многія інтэграцыі пішуць невялікі проксі: лакальную функцыю з назвай __tcfapi унутры фрэйма, якая ператварае выклікі ў паведамленні. Код, напісаны для верхняга акна, тады працуе ў фрэйме без змен.
Event listener паміж фрэймамі
Выклік addEventListener, адпраўлены праз postMessage, — гэта не аднаразовы запыт. CMP будзе дасылаць адказнае паведамленне кожны раз, калі змяняецца стан згоды, і ўсе з тым самым callId. Таму ваш дыспетчар павінен пакідаць гэты callback зарэгістраваным, а не выдаляць яго пасля першага адказу. Забыць пра гэта — класічная памылка: скрыпт у фрэйме чытае згоду адзін раз і не заўважае наступнага адклікання.
Пытанні бяспекі
- Правярайце форму паведамлення. Ігнаруйце любое паведамленне, што не змяшчае чаканай уласцівасці, і асцярожна разбірайце радковыя даныя, бо некаторыя рэалізацыі адпраўляюць JSON-радкі, а не аб’екты.
- Не давярайце наўздагад. Любая старонка можа адпраўляць паведамленні вашаму фрэйму. Адносьцеся да адказаў як да сігналаў згоды, якія трэба ўлічваць, а не як да аўтэнтыфікаваных даных, і ніколі не дазваляйце ім запускаць прывілеяваныя дзеянні.
- Калі магчыма, выкарыстоўвайце канкрэтныя мэтавыя крыніцы. Калі крыніца CMP вядомая, адпраўляйце паведамленне ёй, а не ўсім крыніцам.
Дзе патэрн не працуе
Некаторыя рэкламныя асяроддзі ізалююць крэатывы строгей. Кантэйнеры SafeFrame, iframe у пясочніцы без патрэбных дазволаў і крэатывы, што адлюстроўваюцца ў асобных дакументах, могуць быць не ў стане абысці дрэва фрэймаў або атрымліваць паведамленні. У такіх выпадках сігнал згоды звычайна даводзіцца перадаваць відавочна, напрыклад параметрамі рэкламнага запыту або значэннямі, якія рэкламны сервер перадае крэатыву, як-от параметры gdpr і gdpr_consent, што іх падтрымліваюць многія рэкламныя тэгі.
Чэк-ліст адладкі
- У DevTools верхняга акна пераканайцеся, што фрэймы-лакатары існуюць у панэлі Elements.
- Пераключыце кантэкст кансолі на iframe і праверце, ці дасяжны лакатар адтуль.
- Лагуйце ўваходныя падзеі message у абодвух вокнах, каб пераканацца, што выклікі і адказы ідуць.
- Змяніце згоду ў банеры і праверце, што listener у фрэймах атрымліваюць абнаўленне.
- Пратэстуйце з познай загрузкай CMP, каб пераканацца, што код у фрэйме паўтарае спробы або чакае, а не здаецца адразу.
Ключавыя высновы
- Крос-даменныя фрэймы дасягаюць CMP праз фрэймы __tcfapiLocator і __gppLocator.
- Выклікі і адказы выкарыстоўваюць postMessage з __tcfapiCall/__tcfapiReturn або аналагамі GPP, што супастаўляюцца па callId.
- Трымайце callback listener зарэгістраванымі, каб паступалі наступныя змены згоды.
- Правярайце кожнае паведамленне і не лічыце яго давераным уваходным даным.
- Там, дзе фрэймы цалкам ізаляваны, перадавайце згоду відавочна ў рэкламным запыце.