Por que os teus scripts deben escoitar, non facer polling

Calquera script que dependa do consentimento — unha etiqueta de anuncio, un cargador de analítica, un wrapper de header bidding — precisa saber dúas cousas: se o CMP xa ten unha decisión, e cal é. Un erro habitual é ler unha cookie ao cargar a páxina, ou facer polling ao CMP cun temporizador ata que apareza algo. Ambos enfoques fallan de formas previsibles: o formato da cookie é interno do CMP e pode cambiar, e o polling ou ben se executa demasiado cedo ou ben perde tempo esperando.

O IAB TCF define unha interface JavaScript estándar exactamente para este traballo: a función __tcfapi. Este titorial repasa os comandos que realmente precisas, os eventos que recibirás e os erros que aparecen con máis frecuencia en produción.

O stub e a cola

Espérase que un CMP TCF coloque un pequeno stub na páxina o antes posible, antes de que se cargue o script completo do CMP. O stub define window.__tcfapi e pón en cola calquera chamada feita antes de que o CMP estea listo. Cando o CMP remata de cargar, procesa a cola e responde cada chamada.

Isto é o que fai seguro que outros scripts chamen a __tcfapi inmediatamente: mentres o stub estea na páxina antes ca eles, as súas chamadas non se perden. Se un script lanza un erro porque __tcfapi non está definido, o stub falta ou cárgase demasiado tarde — arranxa a orde de carga en lugar de engadir reintentos.

Os comandos que importan

ping

__tcfapi('ping', 2, callback) devolve o estado básico sen esperar unha decisión do usuario. A resposta inclúe cmpLoaded, un cmpStatus como stub, loading, loaded ou error, e un displayStatus de visible, hidden ou disabled. Tamén informa de gdprApplies unha vez que se coñece. Úsao para o diagnóstico e para decidir se o TCF é relevante para este visitante.

addEventListener

__tcfapi('addEventListener', 2, callback) é o comando que deberían usar a maioría das integracións. O callback recibe un obxecto tcData e unha marca de éxito, e chámase de novo cada vez que cambia o estado do consentimento. Desde o TCF v2.2, esta é a forma recomendada de obter os datos de consentimento; o antigo comando getTCData declarouse obsoleto.

removeEventListener

Cada obxecto tcData leva un listenerId. Pásao a __tcfapi('removeEventListener', 2, callback, listenerId) cando o teu script xa non precise actualizacións — por exemplo, un cargador dun só uso que xa tomou a súa decisión.

Como ler o eventStatus

O campo clave de tcData é eventStatus. Hai tres valores:

• tcloaded — o CMP atopou unha decisión almacenada válida e non se amosará ningún banner. Podes actuar sobre os datos inmediatamente.
• cmpuishown — o banner está a amosarse. Os datos reflicten calquera estado anterior, pero o usuario está a piques de cambialo.
• useractioncomplete — o usuario acaba de facer ou confirmar unha elección. Actúa sobre os datos novos.

Un cargador típico agarda tcloaded ou useractioncomplete, e despois comproba as finalidades e provedores que precisa. Ignora cmpuishown, agás quizais para rexistrar que apareceu un banner.

Comprobar finalidades e provedores

Dentro de tcData, o consentimento e o interese lexítimo expóñense como obxectos indexados por ID:

• tcData.purpose.consents[1] — consentimento para a finalidade 1 (almacenamento no dispositivo).
• tcData.purpose.legitimateInterests[7] — estado do interese lexítimo para a finalidade 7.
• tcData.vendor.consents[ID] e tcData.vendor.legitimateInterests[ID] — estado por provedor, co ID do provedor na Global Vendor List.
• tcData.gdprApplies — se o CMP determinou que o RXPD se aplica a este visitante. Se é false, o teu script debe seguir a súa lóxica non TCF.
• tcData.tcString — a cadea codificada, que lles pasas aos socios que a esperan.

Comproba tanto a finalidade como o provedor. Un consentimento de finalidade sen consentimento de provedor, ou ao revés, non abonda para que a maioría dos provedores traten datos.

Iframes e chamadas entre frames

Os anuncios e os widgets adoitan executarse dentro de iframes que non poden ver o __tcfapi da páxina pai. O TCF resólveo cun protocolo postMessage: o CMP engade un frame chamado __tcfapiLocator á páxina superior, e o código dentro dun iframe pode localizalo, enviar unha mensaxe __tcfapiCall e recibir unha resposta __tcfapiReturn. A maioría dos SDK de anuncios xa o fan. Se escribes o teu propio código de iframe, implementa o mesmo patrón en lugar de ler cookies entre frames.

Erros habituais e como detectalos

1. Actuar sobre cmpuishown. Os scripts que se cargan en canto se dispara calquera callback executaranse antes de que o usuario decida. Filtra por eventStatus.
2. Eliminar o listener demasiado cedo. Se o eliminas despois do primeiro callback, perderás un useractioncomplete posterior e nunca se cargará.
3. Ignorar as retiradas. Os scripts persistentes deben seguir escoitando e deterse ou reconfigurarse cando se retira o consentimento.
4. Ignorar gdprApplies. Fóra das rexións TCF, os obxectos de finalidades poden estar baleiros; tratalo como “sen consentimento” pode desactivar ingresos que tes permitido obter.
5. Non comprobar a marca de éxito. Cando success é falso, rexístrao; normalmente indica unha configuración de CMP rota.

Probar a túa integración

Na consola do navegador, chama a __tcfapi('ping', 2, console.log) para confirmar que o CMP está presente, despois rexistra un listener con console.log como callback e percorre o banner. Deberías ver cmpuishown seguido de useractioncomplete nunha primeira visita, e tcloaded ao recargar. Repite con aceptar todo, rexeitar todo e unha selección personalizada, e confirma que o teu script se comporta correctamente en cada caso.

Ideas clave

• Usa __tcfapi en lugar de ler cookies do CMP ou facer polling.
• Asegúrate de que o stub do CMP se carga antes de calquera script que chame á API.
• Usa addEventListener e actúa só sobre tcloaded ou useractioncomplete.
• Comproba o estado tanto da finalidade como do provedor, e respecta gdprApplies.
• Usa o patrón postMessage de __tcfapiLocator dentro dos iframes.