Zakaj naj vaše skripte poslušajo in ne sprašujejo

Vsaka skripta, ki je odvisna od privolitve — oglasna oznaka, nalagalnik analitike, ovojnica za header bidding — mora vedeti dvoje: ali ima CMP že odločitev in kakšna je ta odločitev. Pogosta napaka je branje piškotka ob nalaganju strani ali spraševanje CMP-ja z odštevalnikom, dokler se nekaj ne pojavi. Oba pristopa se pokvarita na predvidljive načine: format piškotka je notranja zadeva CMP-ja in se lahko spremeni, spraševanje pa se sproži prezgodaj ali izgublja čas z čakanjem.

IAB TCF definira standardni vmesnik JavaScript prav za to nalogo: funkcijo __tcfapi. Ta vadnica vodi skozi ukaze, ki jih resnično potrebujete, dogodke, ki jih boste prejemali, in napake, ki se v produkciji pojavljajo najpogosteje.

Stub in čakalna vrsta

Od CMP-ja TCF se pričakuje, da na stran čim prej postavi majhen stub, preden se naloži celotna skripta CMP. Stub definira window.__tcfapi in v čakalno vrsto postavi vse klice, opravljene, preden je CMP pripravljen. Ko CMP konča nalaganje, vrsto obdela in odgovori na vsak klic.

Zaradi tega lahko druge skripte varno takoj kličejo __tcfapi: dokler je stub na strani pred njimi, njihovi klici ne gredo v izgubo. Če skripta vrže napako, ker __tcfapi ni definiran, stub bodisi manjka bodisi se nalaga prepozno — popravite vrstni red nalaganja namesto dodajanja ponovnih poskusov.

Ukazi, ki so pomembni

ping

__tcfapi('ping', 2, callback) vrne osnovni status, ne da bi čakal na odločitev uporabnika. Odgovor vsebuje cmpLoaded, cmpStatus, kot so stub, loading, loaded ali error, in displayStatus z vrednostjo visible, hidden ali disabled. Poroča tudi gdprApplies, ko je znan. Uporabite ga za diagnostiko in za odločitev, ali je TCF za tega obiskovalca sploh relevanten.

addEventListener

__tcfapi('addEventListener', 2, callback) je ukaz, ki bi ga morala uporabljati večina integracij. Callback prejme objekt tcData in zastavico uspeha ter se znova pokliče vsakič, ko se stanje privolitve spremeni. Od TCF v2.2 je to priporočeni način pridobivanja podatkov o privolitvi; starejši ukaz getTCData je zastarel.

removeEventListener

Vsak objekt tcData nosi listenerId. Posredujte ga v __tcfapi('removeEventListener', 2, callback, listenerId), ko vaša skripta ne potrebuje več posodobitev — na primer enkratni nalagalnik, ki je že sprejel svojo odločitev.

Branje eventStatus

Ključno polje v tcData je eventStatus. Obstajajo tri vrednosti:

• tcloaded — CMP je našel veljavno shranjeno odločitev in pasica ne bo prikazana. S podatki lahko takoj ukrepate.
• cmpuishown — pasica se prikazuje. Podatki odražajo prejšnje stanje, vendar ga bo uporabnik morda kmalu spremenil.
• useractioncomplete — uporabnik je pravkar izbral ali potrdil izbiro. Ukrepajte na podlagi novih podatkov.

Tipičen nalagalnik počaka na tcloaded ali useractioncomplete, nato preveri namene in dobavitelje, ki jih potrebuje. cmpuishown ignorira, razen morda da zabeleži, da se je pasica pojavila.

Preverjanje namenov in dobaviteljev

Znotraj tcData sta privolitev in legitimni interes izpostavljena kot objekta s ključi po ID-ju:

• tcData.purpose.consents[1] — privolitev za namen 1 (shranjevanje v napravi).
• tcData.purpose.legitimateInterests[7] — stanje legitimnega interesa za namen 7.
• tcData.vendor.consents[ID] in tcData.vendor.legitimateInterests[ID] — stanje po dobavitelju, z ID-jem dobavitelja iz Global Vendor List.
• tcData.gdprApplies — ali je CMP ugotovil, da se za tega obiskovalca uporablja GDPR. Če je false, naj vaša skripta sledi svoji logiki brez TCF.
• tcData.tcString — kodirani string, ki ga posredujete partnerjem, ki ga pričakujejo.

Preverite tako namen kot dobavitelja. Privolitev za namen brez privolitve za dobavitelja, ali obratno, večini dobaviteljev ne zadošča za obdelavo podatkov.

Iframei in klici med okvirji

Oglasi in pripomočki pogosto delujejo znotraj iframov, ki ne vidijo __tcfapi nadrejene strani. TCF to rešuje s protokolom postMessage: CMP na vrhnjo stran doda okvir z imenom __tcfapiLocator, koda znotraj iframa pa ga lahko poišče, pošlje sporočilo __tcfapiCall in prejme odgovor __tcfapiReturn. Večina oglasnih SDK-jev to že počne. Če pišete lastno kodo iframa, implementirajte isti vzorec namesto branja piškotkov med okvirji.

Pogoste napake in kako jih opaziti

1. Ukrepanje na cmpuishown. Skripte, ki se naložijo takoj, ko se sproži kateri koli callback, se bodo zagnale, preden se uporabnik odloči. Filtrirajte po eventStatus.
2. Prezgodnja odstranitev poslušalca. Če ga odstranite po prvem callbacku, boste zamudili poznejši useractioncomplete in skripta se nikoli ne naloži.
3. Ignoriranje preklicev. Trajne skripte naj še naprej poslušajo in se ustavijo ali ponovno nastavijo, ko je privolitev preklicana.
4. Ignoriranje gdprApplies. Zunaj regij TCF so objekti namenov lahko prazni; razlaga tega kot “ni privolitve” lahko izklopi prihodek, ki ga smete ustvarjati.
5. Nepreverjanje zastavice uspeha. Ko je success false, to zabeležite; običajno nakazuje pokvarjeno nastavitev CMP-ja.

Preizkušanje integracije

V konzoli brskalnika pokličite __tcfapi('ping', 2, console.log), da potrdite prisotnost CMP-ja, nato registrirajte poslušalca z console.log kot callbackom in se prebijte skozi pasico. Ob prvem obisku bi morali videti cmpuishown, ki mu sledi useractioncomplete, ob ponovnem nalaganju pa tcloaded. Ponovite s sprejemom vsega, zavrnitvijo vsega in po meri prilagojeno izbiro ter potrdite, da se vaša skripta v vsakem primeru obnaša pravilno.

Ključne ugotovitve

• Uporabljajte __tcfapi namesto branja piškotkov CMP ali spraševanja.
• Poskrbite, da se stub CMP naloži pred vsako skripto, ki kliče API.
• Uporabljajte addEventListener in ukrepajte samo na tcloaded ali useractioncomplete.
• Preverite stanje namena in stanje dobavitelja ter upoštevajte gdprApplies.
• Znotraj iframov uporabite vzorec __tcfapiLocator s postMessage.