Zašto bi vaše skripte trebale slušati, a ne anketirati

Svakoj skripti koja ovisi o privoli — oglasnom tagu, učitavaču analitike, omotaču za header bidding — trebaju dvije informacije: ima li CMP već odluku i kakva je ta odluka. Česta je pogreška čitati kolačić pri učitavanju stranice ili anketirati CMP tajmerom dok se nešto ne pojavi. Oba pristupa pucaju na predvidljive načine: format kolačića interna je stvar CMP-a i može se promijeniti, a anketiranje se ili pokrene prerano ili gubi vrijeme čekajući.

IAB TCF definira standardno JavaScript sučelje upravo za taj posao: funkciju __tcfapi. Ovaj tutorijal vodi kroz naredbe koje vam doista trebaju, događaje koje ćete primati i greške koje se najčešće pojavljuju u produkciji.

Stub i red čekanja

Od TCF CMP-a očekuje se da što ranije na stranicu postavi mali stub, prije nego što se učita cijela CMP skripta. Stub definira window.__tcfapi i stavlja u red sve pozive upućene prije nego što je CMP spreman. Kad CMP završi s učitavanjem, obrađuje red i odgovara na svaki poziv.

To omogućuje drugim skriptama da sigurno pozovu __tcfapi odmah: sve dok je stub na stranici prije njih, njihovi pozivi ne propadaju. Ako skripta baci grešku jer __tcfapi nije definiran, stub ili nedostaje ili se učitava prekasno — popravite redoslijed učitavanja umjesto dodavanja ponovnih pokušaja.

Naredbe koje su važne

ping

__tcfapi('ping', 2, callback) vraća osnovni status bez čekanja na odluku korisnika. Odgovor sadrži cmpLoaded, cmpStatus poput stub, loading, loaded ili error, i displayStatus s vrijednošću visible, hidden ili disabled. Također javlja gdprApplies čim postane poznato. Koristite ga za dijagnostiku i da odlučite je li TCF uopće relevantan za ovog posjetitelja.

addEventListener

__tcfapi('addEventListener', 2, callback) je naredba koju bi većina integracija trebala koristiti. Callback prima objekt tcData i zastavicu uspjeha, a poziva se iznova svaki put kad se stanje privole promijeni. Od TCF v2.2 ovo je preporučeni način dobivanja podataka o privoli; starija naredba getTCData je zastarjela.

removeEventListener

Svaki tcData objekt nosi listenerId. Proslijedite ga u __tcfapi('removeEventListener', 2, callback, listenerId) kad vašoj skripti više nisu potrebna ažuriranja — na primjer, jednokratnom učitavaču koji je već donio svoju odluku.

Čitanje eventStatus

Ključno polje u tcData je eventStatus. Postoje tri vrijednosti:

• tcloaded — CMP je pronašao valjanu pohranjenu odluku i banner neće biti prikazan. Možete odmah djelovati na temelju podataka.
• cmpuishown — banner se prikazuje. Podaci odražavaju prethodno stanje, ali korisnik će ga možda uskoro promijeniti.
• useractioncomplete — korisnik je upravo napravio ili potvrdio odabir. Djelujte na temelju novih podataka.

Tipičan učitavač čeka ili tcloaded ili useractioncomplete, a zatim provjerava svrhe i dobavljače koji su mu potrebni. cmpuishown zanemaruje, osim možda da zabilježi da se banner pojavio.

Provjera svrha i dobavljača

Unutar tcData, privola i legitimni interes izloženi su kao objekti s ključevima po ID-u:

• tcData.purpose.consents[1] — privola za svrhu 1 (pohrana na uređaju).
• tcData.purpose.legitimateInterests[7] — status legitimnog interesa za svrhu 7.
• tcData.vendor.consents[ID] i tcData.vendor.legitimateInterests[ID] — status po dobavljaču, uz ID dobavljača iz Global Vendor Liste.
• tcData.gdprApplies — je li CMP utvrdio da se GDPR primjenjuje na ovog posjetitelja. Ako je false, vaša skripta treba slijediti svoju ne-TCF logiku.
• tcData.tcString — kodirani string, koji prosljeđujete partnerima koji ga očekuju.

Provjerite i svrhu i dobavljača. Privola za svrhu bez privole za dobavljača, ili obrnuto, nije dovoljna većini dobavljača za obradu podataka.

Iframeovi i pozivi među okvirima

Oglasi i widgeti često rade unutar iframeova koji ne vide __tcfapi roditeljske stranice. TCF to rješava postMessage protokolom: CMP dodaje okvir pod imenom __tcfapiLocator na vršnu stranicu, a kod unutar iframea može ga pronaći, poslati poruku __tcfapiCall i primiti odgovor __tcfapiReturn. Većina oglasnih SDK-ova to već radi. Ako pišete vlastiti iframe kod, implementirajte isti obrazac umjesto čitanja kolačića između okvira.

Česte greške i kako ih uočiti

1. Djelovanje na cmpuishown. Skripte koje se učitaju čim se aktivira bilo koji callback pokrenut će se prije nego što korisnik odluči. Filtrirajte po eventStatus.
2. Prerano uklanjanje slušatelja. Ako ga uklonite nakon prvog callbacka, propustit ćete kasniji useractioncomplete i nikada nećete učitati skriptu.
3. Zanemarivanje povlačenja. Trajne skripte trebaju nastaviti slušati i zaustaviti se ili rekonfigurirati kad se privola povuče.
4. Zanemarivanje gdprApplies. Izvan TCF regija objekti svrha mogu biti prazni; tumačenje toga kao “nema privole” može ugasiti prihod koji smijete ostvariti.
5. Neprovjeravanje zastavice uspjeha. Kad je success false, zabilježite to; to obično signalizira pokvaren CMP setup.

Testiranje integracije

U konzoli preglednika pozovite __tcfapi('ping', 2, console.log) da potvrdite da je CMP prisutan, zatim registrirajte slušatelja s console.log kao callbackom i prođite kroz banner. Pri prvom posjetu trebali biste vidjeti cmpuishown, a zatim useractioncomplete, a pri ponovnom učitavanju tcloaded. Ponovite s prihvaćanjem svega, odbijanjem svega i prilagođenim odabirom te potvrdite da se vaša skripta u svakom slučaju ponaša ispravno.

Ključni zaključci

• Koristite __tcfapi umjesto čitanja CMP kolačića ili anketiranja.
• Pobrinite se da se CMP stub učita prije svake skripte koja poziva API.
• Koristite addEventListener i djelujte samo na tcloaded ili useractioncomplete.
• Provjerite i status svrhe i status dobavljača te poštujte gdprApplies.
• Unutar iframeova koristite obrazac __tcfapiLocator s postMessageom.