De ce scripturile tale trebuie să asculte, nu să facă polling

Orice script care depinde de consimțământ — un tag de reclamă, un loader de analitică, un wrapper de header bidding — trebuie să știe două lucruri: dacă CMP-ul are deja o decizie și care este aceasta. O greșeală frecventă este să citești un cookie la încărcarea paginii sau să faci polling către CMP cu un temporizator până apare ceva. Ambele abordări eșuează în moduri previzibile: formatul cookie-ului este intern CMP-ului și se poate schimba, iar polling-ul fie se declanșează prea devreme, fie pierde timp așteptând.

IAB TCF definește o interfață JavaScript standard exact pentru această sarcină: funcția __tcfapi. Acest tutorial parcurge comenzile de care ai nevoie în realitate, evenimentele pe care le vei primi și erorile care apar cel mai des în producție.

Stub-ul și coada

Se așteaptă ca un CMP TCF să plaseze un mic stub în pagină cât mai devreme, înainte ca scriptul complet al CMP-ului să se încarce. Stub-ul definește window.__tcfapi și pune în coadă orice apel făcut înainte ca CMP-ul să fie gata. Când CMP-ul termină încărcarea, procesează coada și răspunde la fiecare apel.

Aceasta este ceea ce face sigur ca alte scripturi să apeleze __tcfapi imediat: atâta timp cât stub-ul este în pagină înaintea lor, apelurile lor nu se pierd. Dacă un script aruncă o eroare deoarece __tcfapi este nedefinit, stub-ul fie lipsește, fie se încarcă prea târziu — repară ordinea de încărcare în loc să adaugi reîncercări.

Comenzile care contează

ping

__tcfapi('ping', 2, callback) returnează starea de bază fără să aștepte o decizie a utilizatorului. Răspunsul include cmpLoaded, un cmpStatus precum stub, loading, loaded sau error și un displayStatus de tip visible, hidden sau disabled. Raportează și gdprApplies odată ce este cunoscut. Folosește-l pentru diagnosticare și pentru a decide dacă TCF este relevant pentru acest vizitator.

addEventListener

__tcfapi('addEventListener', 2, callback) este comanda pe care ar trebui s-o folosească majoritatea integrărilor. Callback-ul primește un obiect tcData și un indicator de succes și este apelat din nou de fiecare dată când se schimbă starea consimțământului. Începând cu TCF v2.2, aceasta este modalitatea recomandată de a obține datele de consimțământ; vechea comandă getTCData a fost depreciată.

removeEventListener

Fiecare obiect tcData conține un listenerId. Transmite-l către __tcfapi('removeEventListener', 2, callback, listenerId) când scriptul tău nu mai are nevoie de actualizări — de exemplu, un loader unic care și-a luat deja decizia.

Citirea eventStatus

Câmpul-cheie din tcData este eventStatus. Există trei valori:

• tcloaded — CMP-ul a găsit o decizie stocată validă și nu va fi afișat niciun banner. Poți acționa imediat asupra datelor.
• cmpuishown — bannerul este afișat. Datele reflectă orice stare anterioară, dar utilizatorul este pe punctul de a o schimba.
• useractioncomplete — utilizatorul tocmai a făcut sau a confirmat o alegere. Acționează asupra datelor noi.

Un loader tipic așteaptă fie tcloaded, fie useractioncomplete, apoi verifică scopurile și furnizorii de care are nevoie. Ignoră cmpuishown, cu excepția eventualei înregistrări că a apărut un banner.

Verificarea scopurilor și a furnizorilor

În tcData, consimțământul și interesul legitim sunt expuse ca obiecte indexate după ID:

• tcData.purpose.consents[1] — consimțământul pentru scopul 1 (stocarea pe dispozitiv).
• tcData.purpose.legitimateInterests[7] — starea interesului legitim pentru scopul 7.
• tcData.vendor.consents[ID] și tcData.vendor.legitimateInterests[ID] — starea pe furnizor, folosind ID-ul furnizorului din Global Vendor List.
• tcData.gdprApplies — dacă CMP-ul a stabilit că GDPR se aplică acestui vizitator. Dacă este false, scriptul tău ar trebui să urmeze logica sa non-TCF.
• tcData.tcString — șirul codificat, pe care îl transmiți partenerilor care îl așteaptă.

Verifică atât scopul, cât și furnizorul. Un consimțământ pentru scop fără consimțământ pentru furnizor, sau invers, nu este suficient pentru ca majoritatea furnizorilor să prelucreze date.

Iframe-uri și apeluri între cadre

Reclamele și widget-urile rulează adesea în iframe-uri care nu pot vedea __tcfapi al paginii părinte. TCF rezolvă asta cu un protocol postMessage: CMP-ul adaugă un cadru numit __tcfapiLocator în pagina de sus, iar codul dintr-un iframe îl poate localiza, poate trimite un mesaj __tcfapiCall și poate primi un răspuns __tcfapiReturn. Majoritatea SDK-urilor de reclame fac deja asta. Dacă scrii propriul cod de iframe, implementează același model în loc să citești cookie-uri între cadre.

Erori frecvente și cum le identifici

1. Acționarea pe cmpuishown. Scripturile care se încarcă imediat ce se declanșează orice callback vor rula înainte ca utilizatorul să decidă. Filtrează după eventStatus.
2. Eliminarea prea devreme a listener-ului. Dacă îl elimini după primul callback, vei rata un useractioncomplete ulterior și nu se va încărca niciodată.
3. Ignorarea retragerilor. Scripturile persistente ar trebui să continue să asculte și să se oprească sau să se reconfigureze atunci când consimțământul este retras.
4. Ignorarea gdprApplies. În afara regiunilor TCF, obiectele de scopuri pot fi goale; tratarea acestui lucru drept “fără consimțământ” poate opri venituri pe care ai voie să le obții.
5. Neverificarea indicatorului de succes. Când success este fals, înregistrează-l; de obicei semnalează o configurare defectuoasă a CMP-ului.

Testarea integrării tale

În consola browserului, apelează __tcfapi('ping', 2, console.log) pentru a confirma că CMP-ul este prezent, apoi înregistrează un listener cu console.log ca callback și parcurge bannerul. Ar trebui să vezi cmpuishown urmat de useractioncomplete la prima vizită și tcloaded la reîncărcare. Repetă cu accept-all, reject-all și o selecție personalizată și confirmă că scriptul tău se comportă corect în fiecare caz.

Concluzii-cheie

• Folosește __tcfapi în loc să citești cookie-urile CMP-ului sau să faci polling.
• Asigură-te că stub-ul CMP se încarcă înaintea oricărui script care apelează API-ul.
• Folosește addEventListener și acționează doar pe tcloaded sau useractioncomplete.
• Verifică starea atât a scopului, cât și a furnizorului și respectă gdprApplies.
• Folosește modelul postMessage __tcfapiLocator în interiorul iframe-urilor.