Pourquoi vos scripts doivent écouter, pas scruter

Tout script qui dépend du consentement — une balise publicitaire, un chargeur d’analytique, un wrapper de header bidding — doit savoir deux choses : si le CMP a déjà une décision, et laquelle. Une erreur courante consiste à lire un cookie au chargement de la page, ou à interroger le CMP en boucle avec un minuteur jusqu’à ce que quelque chose apparaisse. Ces deux approches échouent de façon prévisible : le format du cookie est interne au CMP et peut changer, et l’interrogation en boucle se déclenche soit trop tôt, soit fait perdre du temps à attendre.

L’IAB TCF définit une interface JavaScript standard pour exactement ce travail : la fonction __tcfapi. Ce tutoriel passe en revue les commandes dont vous avez réellement besoin, les événements que vous recevrez et les bugs qui apparaissent le plus souvent en production.

Le stub et la file d’attente

Un CMP TCF doit placer sur la page un petit stub aussi tôt que possible, avant le chargement du script complet du CMP. Le stub définit window.__tcfapi et met en file d’attente les appels effectués avant que le CMP soit prêt. Lorsque le CMP a fini de se charger, il traite la file et répond à chaque appel.

C’est ce qui permet à d’autres scripts d’appeler __tcfapi immédiatement sans risque : tant que le stub est dans la page avant eux, leurs appels ne sont pas perdus. Si un script déclenche une erreur parce que __tcfapi est indéfini, le stub est soit absent, soit chargé trop tard — corrigez l’ordre de chargement plutôt que d’ajouter des tentatives.

Les commandes qui comptent

ping

__tcfapi('ping', 2, callback) renvoie un état de base sans attendre la décision de l’utilisateur. La réponse comprend cmpLoaded, un cmpStatus tel que stub, loading, loaded ou error, et un displayStatus valant visible, hidden ou disabled. Elle indique aussi gdprApplies dès que la valeur est connue. Utilisez-la pour le diagnostic et pour décider si le TCF est pertinent pour ce visiteur.

addEventListener

__tcfapi('addEventListener', 2, callback) est la commande que la plupart des intégrations devraient utiliser. Le callback reçoit un objet tcData et un indicateur de succès, et il est rappelé chaque fois que l’état du consentement change. Depuis le TCF v2.2, c’est la méthode recommandée pour obtenir les données de consentement ; l’ancienne commande getTCData a été dépréciée.

removeEventListener

Chaque objet tcData porte un listenerId. Transmettez-le à __tcfapi('removeEventListener', 2, callback, listenerId) lorsque votre script n’a plus besoin de mises à jour — par exemple un chargeur à usage unique qui a déjà pris sa décision.

Lire eventStatus

Le champ clé de tcData est eventStatus. Il a trois valeurs :

• tcloaded — le CMP a trouvé une décision stockée valide et aucune bannière ne sera affichée. Vous pouvez agir immédiatement sur les données.
• cmpuishown — la bannière est en cours d’affichage. Les données reflètent l’état précédent éventuel, mais l’utilisateur est peut-être sur le point de le modifier.
• useractioncomplete — l’utilisateur vient de faire ou de confirmer un choix. Agissez sur les nouvelles données.

Un chargeur typique attend soit tcloaded, soit useractioncomplete, puis vérifie les finalités et les fournisseurs dont il a besoin. Il ignore cmpuishown, sauf peut-être pour consigner qu’une bannière est apparue.

Vérifier les finalités et les fournisseurs

Dans tcData, le consentement et l’intérêt légitime sont exposés sous forme d’objets indexés par ID :

• tcData.purpose.consents[1] — consentement pour la finalité 1 (stockage sur l’appareil).
• tcData.purpose.legitimateInterests[7] — état de l’intérêt légitime pour la finalité 7.
• tcData.vendor.consents[ID] et tcData.vendor.legitimateInterests[ID] — état par fournisseur, à partir de l’ID du fournisseur dans la Global Vendor List.
• tcData.gdprApplies — indique si le CMP a déterminé que le RGPD s’applique à ce visiteur. Si la valeur est false, votre script doit suivre sa logique hors TCF.
• tcData.tcString — la chaîne encodée, que vous transmettez aux partenaires qui l’attendent.

Vérifiez à la fois la finalité et le fournisseur. Un consentement de finalité sans consentement du fournisseur, ou l’inverse, ne suffit pas à la plupart des fournisseurs pour traiter des données.

Iframes et appels entre frames

Les publicités et les widgets s’exécutent souvent dans des iframes qui ne peuvent pas voir le __tcfapi de la page parente. Le TCF résout cela avec un protocole postMessage : le CMP ajoute à la page principale une frame nommée __tcfapiLocator, et le code d’une iframe peut la localiser, envoyer un message __tcfapiCall et recevoir une réponse __tcfapiReturn. La plupart des SDK publicitaires le font déjà. Si vous écrivez votre propre code d’iframe, appliquez le même schéma plutôt que de lire des cookies entre frames.

Bugs courants et comment les repérer

1. Agir sur cmpuishown. Les scripts qui se chargent dès qu’un callback se déclenche s’exécuteront avant que l’utilisateur ne décide. Filtrez sur eventStatus.
2. Retirer l’écouteur trop tôt. Si vous le retirez après le premier callback, vous manquerez un useractioncomplete ultérieur et ne chargerez jamais.
3. Ignorer les retraits. Les scripts persistants doivent continuer à écouter et s’arrêter ou se reconfigurer lorsque le consentement est retiré.
4. Ignorer gdprApplies. Hors des régions TCF, les objets de finalités peuvent être vides ; les traiter comme “pas de consentement” peut couper des revenus que vous avez le droit de générer.
5. Ne pas vérifier l’indicateur de succès. Lorsque success vaut false, consignez-le ; cela signale généralement une configuration de CMP défaillante.

Tester votre intégration

Dans la console du navigateur, appelez __tcfapi('ping', 2, console.log) pour confirmer que le CMP est présent, puis enregistrez un écouteur avec console.log comme callback et parcourez la bannière. Vous devriez voir cmpuishown suivi de useractioncomplete lors d’une première visite, et tcloaded après un rechargement. Répétez avec tout accepter, tout refuser et une sélection personnalisée, et confirmez que votre script se comporte correctement dans chaque cas.

Points clés à retenir

• Utilisez __tcfapi plutôt que de lire les cookies du CMP ou de scruter en boucle.
• Assurez-vous que le stub du CMP se charge avant tout script qui appelle l’API.
• Utilisez addEventListener et n’agissez que sur tcloaded ou useractioncomplete.
• Vérifiez à la fois l’état de la finalité et celui du fournisseur, et respectez gdprApplies.
• Utilisez le schéma postMessage de __tcfapiLocator dans les iframes.