Чаму скрыптам варта слухаць, а не апытваць

Любому скрыпту, што залежыць ад згоды — рэкламнаму тэгу, загрузчыку аналітыкі, абгортцы header bidding, — трэба ведаць дзве рэчы: ці ёсць у CMP ужо рашэнне і якое яно. Распаўсюджаная памылка — чытаць cookie падчас загрузкі старонкі або апытваць CMP па таймеры, пакуль нешта не з'явіцца. Абодва падыходы ламаюцца прадказальна: фармат cookie ўнутраны для CMP і можа змяніцца, а апытванне або спрацоўвае занадта рана, або дарэмна траціць час на чаканне.

IAB TCF вызначае для гэтай задачы стандартны JavaScript-інтэрфейс — функцыю __tcfapi. У гэтым кіраўніцтве разгледжаны каманды, якія сапраўды патрэбны, падзеі, якія вы будзеце атрымліваць, і памылкі, што часцей за ўсё сустракаюцца ў прадакшне.

Заглушка і чарга

CMP на аснове TCF павінен як мага раней размясціць на старонцы невялікую заглушку (stub), яшчэ да загрузкі асноўнага скрыпта CMP. Заглушка вызначае window.__tcfapi і ставіць у чаргу ўсе выклікі, зробленыя да гатоўнасці CMP. Калі CMP завяршае загрузку, ён апрацоўвае чаргу і адказвае на кожны выклік.

Менавіта дзякуючы гэтаму іншыя скрыпты могуць бяспечна выклікаць __tcfapi адразу: пакуль заглушка знаходзіцца на старонцы раней за іх, іх выклікі не губляюцца. Калі скрыпт падае з-за таго, што __tcfapi не вызначана, заглушка або адсутнічае, або загружаецца занадта позна — выпраўляйце парадак загрузкі, а не дадавайце паўторныя спробы.

Каманды, якія маюць значэнне

ping

__tcfapi('ping', 2, callback) вяртае базавы статус, не чакаючы рашэння карыстальніка. Адказ утрымлівае cmpLoaded, cmpStatus са значэннямі накшталт stub, loading, loaded або error, а таксама displayStatus са значэннем visible, hidden або disabled. Ён таксама паведамляе gdprApplies, калі гэта становіцца вядома. Выкарыстоўвайце яго для дыягностыкі і каб зразумець, ці актуальны TCF для гэтага наведвальніка наогул.

addEventListener

__tcfapi('addEventListener', 2, callback) — каманда, якую павінна выкарыстоўваць большасць інтэграцый. Калбэк атрымлівае аб'ект tcData і сцяжок поспеху і выклікаецца зноў кожны раз, калі змяняецца стан згоды. Пачынаючы з TCF v2.2 гэта рэкамендаваны спосаб атрымання даных пра згоду; старую каманду getTCData прызналі састарэлай.

removeEventListener

Кожны аб'ект tcData утрымлівае listenerId. Перадайце яго ў __tcfapi('removeEventListener', 2, callback, listenerId), калі вашаму скрыпту больш не патрэбныя абнаўленні — напрыклад, аднаразоваму загрузчыку, які ўжо прыняў рашэнне.

Чытанне eventStatus

Ключавое поле ў tcData — eventStatus. Яно мае тры значэнні:

• tcloaded — CMP знайшоў сапраўднае захаванае рашэнне, і банер паказвацца не будзе. Можна адразу дзейнічаць на аснове даных.
• cmpuishown — банер адлюстроўваецца. Даныя адлюстроўваюць папярэдні стан, але карыстальнік вось-вось можа яго змяніць.
• useractioncomplete — карыстальнік толькі што зрабіў або пацвердзіў выбар. Дзейнічайце па новых данных.

Тыповы загрузчык чакае tcloaded або useractioncomplete, потым правярае патрэбныя яму мэты і вендараў. Падзею cmpuishown ён ігнаруе, хіба што запісвае ў лог, што банер з'явіўся.

Праверка мэт і вендараў

Унутры tcData згода і законны інтарэс прадстаўлены аб'ектамі з ключамі-ідэнтыфікатарамі:

• tcData.purpose.consents[1] — згода на мэту 1 (захоўванне на прыладзе).
• tcData.purpose.legitimateInterests[7] — статус законнага інтарэсу для мэты 7.
• tcData.vendor.consents[ID] і tcData.vendor.legitimateInterests[ID] — статус па кожным вендары з выкарыстаннем яго ідэнтыфікатара ў Global Vendor List.
• tcData.gdprApplies — ці вызначыў CMP, што да гэтага наведвальніка прымяняецца GDPR. Калі значэнне false, скрыпту варта выконваць логіку без TCF.
• tcData.tcString — закадаваны радок, які вы перадаяце партнёрам, што яго чакаюць.

Правярайце і мэту, і вендара. Згоды на мэту без згоды для вендара (або наадварот) для большасці вендараў недастаткова, каб апрацоўваць даныя.

Iframe і міжфрэймавыя выклікі

Рэклама і віджэты часта працуюць унутры iframe, якія не бачаць __tcfapi бацькоўскай старонкі. TCF вырашае гэта пратаколам postMessage: CMP дадае на верхнюю старонку фрэйм з імем __tcfapiLocator, а код унутры iframe можа знайсці яго, адправіць паведамленне __tcfapiCall і атрымаць адказ __tcfapiReturn. Большасць рэкламных SDK ужо гэта робяць. Калі вы пішаце ўласны код для iframe, рэалізуйце той самы шаблон, а не чытайце cookie паміж фрэймамі.

Частыя памылкі і як іх заўважыць

1. Дзеянні па cmpuishown. Скрыпты, што загружаюцца пры любым спрацоўванні калбэка, запусцяцца да рашэння карыстальніка. Фільтруйце па eventStatus.
2. Занадта ранняе выдаленне слухача. Калі выдаліць яго пасля першага калбэка, вы прапусціце наступны useractioncomplete і так і не загрузіцеся.
3. Ігнараванне адклікання згоды. Скрыпты, што працуюць пастаянна, павінны працягваць слухаць і спыняцца або перанастройвацца, калі згоду адклікана.
4. Ігнараванне gdprApplies. За межамі рэгіёнаў TCF аб'екты мэт могуць быць пустымі; лічыць гэта «адсутнасцю згоды» значыць адключыць даход, які вам дазволена атрымліваць.
5. Адсутнасць праверкі сцяжка поспеху. Калі success роўна false, запішыце гэта ў лог; звычайна гэта сігнал пра няспраўную наладу CMP.

Тэсціраванне інтэграцыі

У кансолі браўзера выклічце __tcfapi('ping', 2, console.log), каб пераканацца, што CMP на месцы, потым зарэгіструйце слухача з console.log у якасці калбэка і прайдзіце па банеры. Падчас першага візіту вы павінны ўбачыць cmpuishown, а за ім useractioncomplete, а пасля перазагрузкі — tcloaded. Паўтарыце для варыянтаў «прыняць усё», «адхіліць усё» і ўласнага выбару і пераканайцеся, што скрыпт карэктна працуе ў кожным выпадку.

Галоўныя высновы

• Выкарыстоўвайце __tcfapi замест чытання cookie CMP або апытвання.
• Пераканайцеся, што заглушка CMP загружаецца раней за любы скрыпт, які выклікае API.
• Выкарыстоўвайце addEventListener і дзейнічайце толькі па tcloaded або useractioncomplete.
• Правярайце статус і мэты, і вендара і ўлічвайце gdprApplies.
• Унутры iframe ужывайце шаблон postMessage з __tcfapiLocator.