Pse skriptet tuaja duhet të dëgjojnë, jo të bëjnë polling

Çdo skript që varet nga pëlqimi — një etiketë reklame, një ngarkues analitike, një wrapper i header bidding — duhet të dijë dy gjëra: nëse CMP-ja ka tashmë një vendim, dhe cili është ai. Një gabim i zakonshëm është leximi i një cookie-je gjatë ngarkimit të faqes, ose polling-u i CMP-së me një kohëmatës derisa të shfaqet diçka. Të dyja qasjet dështojnë në mënyra të parashikueshme: formati i cookie-s është i brendshëm për CMP-në dhe mund të ndryshojë, ndërsa polling-u ose aktivizohet shumë herët ose humb kohë duke pritur.

IAB TCF përcakton një ndërfaqe standarde JavaScript pikërisht për këtë punë: funksionin __tcfapi. Ky tutorial përshkon komandat që ju duhen realisht, ngjarjet që do të merrni dhe gabimet që shfaqen më shpesh në prodhim.

Stub-i dhe radha

Pritet që një CMP TCF të vendosë një stub të vogël në faqe sa më herët të jetë e mundur, para se të ngarkohet skripti i plotë i CMP-së. Stub-i përcakton window.__tcfapi dhe vë në radhë çdo thirrje të bërë përpara se CMP-ja të jetë gati. Kur CMP-ja përfundon ngarkimin, ajo përpunon radhën dhe i përgjigjet çdo thirrjeje.

Kjo është ajo që e bën të sigurt që skriptet e tjera të thërrasin __tcfapi menjëherë: për sa kohë stub-i është në faqe para tyre, thirrjet e tyre nuk humbin. Nëse një skript hedh gabim sepse __tcfapi është i papërcaktuar, stub-i ose mungon ose ngarkohet shumë vonë — rregulloni rendin e ngarkimit në vend që të shtoni riprova.

Komandat që kanë rëndësi

ping

__tcfapi('ping', 2, callback) kthen gjendjen bazë pa pritur një vendim të përdoruesit. Përgjigjja përfshin cmpLoaded, një cmpStatus si stub, loading, loaded ose error, dhe një displayStatus me vlerë visible, hidden ose disabled. Raporton edhe gdprApplies sapo të dihet. Përdoreni për diagnostikim dhe për të vendosur nëse TCF është i rëndësishëm për këtë vizitor.

addEventListener

__tcfapi('addEventListener', 2, callback) është komanda që duhet të përdorin shumica e integrimeve. Callback-u merr një objekt tcData dhe një shenjë suksesi, dhe thirret përsëri sa herë ndryshon gjendja e pëlqimit. Që nga TCF v2.2, ky është mënyra e rekomanduar për të marrë të dhënat e pëlqimit; komanda e vjetër getTCData u shpall e vjetëruar.

removeEventListener

Çdo objekt tcData mban një listenerId. Jepeni te __tcfapi('removeEventListener', 2, callback, listenerId) kur skripti juaj nuk ka më nevojë për përditësime — për shembull, një ngarkues njëpërdorimsh që e ka marrë tashmë vendimin.

Leximi i eventStatus

Fusha kyçe në tcData është eventStatus. Ka tri vlera:

• tcloaded — CMP-ja gjeti një vendim të ruajtur të vlefshëm dhe nuk do të shfaqet asnjë baner. Mund të veproni menjëherë mbi të dhënat.
• cmpuishown — baneri po shfaqet. Të dhënat pasqyrojnë çdo gjendje të mëparshme, por përdoruesi mund të jetë gati ta ndryshojë.
• useractioncomplete — përdoruesi sapo ka bërë ose konfirmuar një zgjedhje. Veproni mbi të dhënat e reja.

Një ngarkues tipik pret ose tcloaded ose useractioncomplete, pastaj kontrollon qëllimet dhe furnitorët që i duhen. Ai e shpërfill cmpuishown, përveç ndoshta për të regjistruar se u shfaq një baner.

Kontrollimi i qëllimeve dhe furnitorëve

Brenda tcData, pëlqimi dhe interesi legjitim ekspozohen si objekte të indeksuara sipas ID-së:

• tcData.purpose.consents[1] — pëlqimi për Qëllimin 1 (ruajtja në pajisje).
• tcData.purpose.legitimateInterests[7] — gjendja e interesit legjitim për Qëllimin 7.
• tcData.vendor.consents[ID] dhe tcData.vendor.legitimateInterests[ID] — gjendja për çdo furnitor, me ID-në e furnitorit në Global Vendor List.
• tcData.gdprApplies — nëse CMP-ja ka përcaktuar që GDPR zbatohet për këtë vizitor. Nëse është false, skripti juaj duhet të ndjekë logjikën e vet jo-TCF.
• tcData.tcString — vargu i koduar, që ua kaloni partnerëve që e presin.

Kontrolloni si qëllimin ashtu edhe furnitorin. Një pëlqim qëllimi pa pëlqim furnitori, ose e kundërta, nuk mjafton që shumica e furnitorëve të përpunojnë të dhëna.

Iframe dhe thirrjet ndërmjet frame-ve

Reklamat dhe miniaplikimet shpesh punojnë brenda iframe-ve që nuk e shohin __tcfapi të faqes mëmë. TCF e zgjidh këtë me një protokoll postMessage: CMP-ja shton një frame me emrin __tcfapiLocator te faqja kryesore, dhe kodi brenda një iframe-i mund ta gjejë, të dërgojë një mesazh __tcfapiCall dhe të marrë një përgjigje __tcfapiReturn. Shumica e SDK-ve të reklamave e bëjnë tashmë këtë. Nëse shkruani kodin tuaj të iframe-it, zbatoni të njëjtin model në vend që të lexoni cookie ndërmjet frame-ve.

Gabimet e zakonshme dhe si t'i dallojmë

1. Veprimi mbi cmpuishown. Skriptet që ngarkohen sapo të aktivizohet çdo callback do të ekzekutohen para se përdoruesi të vendosë. Filtroni sipas eventStatus.
2. Heqja e listener-it shumë herët. Nëse e hiqni pas callback-ut të parë, do të humbisni një useractioncomplete të mëvonshëm dhe nuk do të ngarkohet kurrë.
3. Shpërfillja e tërheqjeve. Skriptet e qëndrueshme duhet të vazhdojnë të dëgjojnë dhe të ndalen ose të rikonfigurohen kur tërhiqet pëlqimi.
4. Shpërfillja e gdprApplies. Jashtë rajoneve TCF, objektet e qëllimeve mund të jenë bosh; ta trajtoni këtë si “pa pëlqim” mund të fikë të ardhura që ju lejohet t'i fitoni.
5. Mosnjohja e shenjës së suksesit. Kur success është false, regjistrojeni; zakonisht tregon një konfigurim të prishur të CMP-së.

Testimi i integrimit tuaj

Në konsolën e shfletuesit, thirrni __tcfapi('ping', 2, console.log) për të konfirmuar që CMP-ja është e pranishme, pastaj regjistroni një listener me console.log si callback dhe kaloni nëpër baner. Duhet të shihni cmpuishown pasuar nga useractioncomplete në vizitën e parë, dhe tcloaded pas ringarkimit. Përsëritni me pranim të gjithçkaje, refuzim të gjithçkaje dhe një përzgjedhje të personalizuar, dhe konfirmoni që skripti juaj sillet saktë në secilin rast.

Pikat kryesore

• Përdorni __tcfapi në vend që të lexoni cookie të CMP-së ose të bëni polling.
• Sigurohuni që stub-i i CMP-së ngarkohet para çdo skripti që thërret API-n.
• Përdorni addEventListener dhe veproni vetëm mbi tcloaded ose useractioncomplete.
• Kontrolloni gjendjen si të qëllimit ashtu edhe të furnitorit, dhe respektoni gdprApplies.
• Përdorni modelin postMessage __tcfapiLocator brenda iframe-ve.