Per què els teus scripts han d'escoltar, no fer polling

Qualsevol script que depengui del consentiment — una etiqueta d'anunci, un carregador d'analítica, un wrapper de header bidding — necessita saber dues coses: si el CMP ja té una decisió, i quina és. Un error habitual és llegir una cookie en carregar la pàgina, o fer polling al CMP amb un temporitzador fins que aparegui alguna cosa. Tots dos enfocaments fallen de maneres previsibles: el format de la cookie és intern del CMP i pot canviar, i el polling o bé s'executa massa aviat o bé perd temps esperant.

L'IAB TCF defineix una interfície JavaScript estàndard exactament per a aquesta feina: la funció __tcfapi. Aquest tutorial repassa les ordres que realment necessites, els esdeveniments que rebràs i els errors que apareixen més sovint en producció.

L'stub i la cua

S'espera que un CMP TCF col·loqui un petit stub a la pàgina el més aviat possible, abans que es carregui l'script complet del CMP. L'stub defineix window.__tcfapi i posa en cua qualsevol crida feta abans que el CMP estigui a punt. Quan el CMP acaba de carregar-se, processa la cua i respon cada crida.

Això és el que fa segur que altres scripts cridin __tcfapi immediatament: sempre que l'stub sigui a la pàgina abans que ells, les seves crides no es perden. Si un script llança un error perquè __tcfapi no està definit, l'stub falta o es carrega massa tard — arregla l'ordre de càrrega en lloc d'afegir reintents.

Les ordres que importen

ping

__tcfapi('ping', 2, callback) retorna l'estat bàsic sense esperar una decisió de l'usuari. La resposta inclou cmpLoaded, un cmpStatus com ara stub, loading, loaded o error, i un displayStatus de visible, hidden o disabled. També informa de gdprApplies un cop es coneix. Fes-lo servir per al diagnòstic i per decidir si el TCF és rellevant per a aquest visitant.

addEventListener

__tcfapi('addEventListener', 2, callback) és l'ordre que haurien d'utilitzar la majoria d'integracions. El callback rep un objecte tcData i un indicador d'èxit, i es torna a cridar cada vegada que canvia l'estat del consentiment. Des del TCF v2.2, aquesta és la manera recomanada d'obtenir les dades de consentiment; l'antiga ordre getTCData es va declarar obsoleta.

removeEventListener

Cada objecte tcData porta un listenerId. Passa'l a __tcfapi('removeEventListener', 2, callback, listenerId) quan el teu script ja no necessiti actualitzacions — per exemple, un carregador d'un sol ús que ja ha pres la seva decisió.

Com llegir l'eventStatus

El camp clau de tcData és eventStatus. Hi ha tres valors:

• tcloaded — el CMP ha trobat una decisió emmagatzemada vàlida i no es mostrarà cap bàner. Pots actuar sobre les dades immediatament.
• cmpuishown — s'està mostrant el bàner. Les dades reflecteixen qualsevol estat anterior, però l'usuari està a punt de canviar-lo.
• useractioncomplete — l'usuari acaba de fer o confirmar una elecció. Actua sobre les dades noves.

Un carregador típic espera tcloaded o useractioncomplete, i després comprova els propòsits i proveïdors que necessita. Ignora cmpuishown, tret potser per registrar que ha aparegut un bàner.

Comprovar propòsits i proveïdors

Dins de tcData, el consentiment i l'interès legítim s'exposen com a objectes indexats per ID:

• tcData.purpose.consents[1] — consentiment per al propòsit 1 (emmagatzematge al dispositiu).
• tcData.purpose.legitimateInterests[7] — estat de l'interès legítim per al propòsit 7.
• tcData.vendor.consents[ID] i tcData.vendor.legitimateInterests[ID] — estat per proveïdor, amb l'ID del proveïdor a la Global Vendor List.
• tcData.gdprApplies — si el CMP ha determinat que el RGPD s'aplica a aquest visitant. Si és false, el teu script ha de seguir la seva lògica no TCF.
• tcData.tcString — la cadena codificada, que passes als socis que l'esperen.

Comprova tant el propòsit com el proveïdor. Un consentiment de propòsit sense consentiment de proveïdor, o a la inversa, no és suficient perquè la majoria de proveïdors tractin dades.

Iframes i crides entre frames

Els anuncis i els widgets sovint s'executen dins d'iframes que no poden veure el __tcfapi de la pàgina pare. El TCF ho resol amb un protocol postMessage: el CMP afegeix un frame anomenat __tcfapiLocator a la pàgina superior, i el codi dins d'un iframe el pot localitzar, enviar un missatge __tcfapiCall i rebre una resposta __tcfapiReturn. La majoria d'SDK d'anuncis ja ho fan. Si escrius el teu propi codi d'iframe, implementa el mateix patró en lloc de llegir cookies entre frames.

Errors habituals i com detectar-los

1. Actuar sobre cmpuishown. Els scripts que es carreguen tan bon punt es dispara qualsevol callback s'executaran abans que l'usuari decideixi. Filtra per eventStatus.
2. Eliminar el listener massa aviat. Si l'elimines després del primer callback, et perdràs un useractioncomplete posterior i mai no es carregarà.
3. Ignorar les retirades. Els scripts persistents han de seguir escoltant i aturar-se o reconfigurar-se quan es retira el consentiment.
4. Ignorar gdprApplies. Fora de les regions TCF, els objectes de propòsits poden estar buits; tractar-ho com a “sense consentiment” pot desactivar ingressos que tens permès obtenir.
5. No comprovar l'indicador d'èxit. Quan success és fals, registra-ho; normalment indica una configuració de CMP trencada.

Provar la teva integració

A la consola del navegador, crida __tcfapi('ping', 2, console.log) per confirmar que el CMP hi és, després registra un listener amb console.log com a callback i recorre el bàner. Hauries de veure cmpuishown seguit de useractioncomplete en una primera visita, i tcloaded en tornar a carregar. Repeteix amb acceptar-ho tot, rebutjar-ho tot i una selecció personalitzada, i confirma que el teu script es comporta correctament en cada cas.

Idees clau

• Fes servir __tcfapi en lloc de llegir cookies del CMP o fer polling.
• Assegura't que l'stub del CMP es carrega abans de qualsevol script que cridi l'API.
• Fes servir addEventListener i actua només sobre tcloaded o useractioncomplete.
• Comprova l'estat tant del propòsit com del proveïdor, i respecta gdprApplies.
• Fes servir el patró postMessage de __tcfapiLocator dins dels iframes.