Le consentement dans les iframes cross-origin : le schéma __tcfapiLocator et __gppLocator

Le problème : le consentement vit dans la fenêtre de niveau supérieur

Un CMP s'exécute sur votre page, dans la fenêtre de niveau supérieur. Une grande partie de votre publicité, non. Les créations display, le rich media, les moteurs de rendu de header bidding et de nombreux widgets tiers s'exécutent dans des iframes, souvent sur une autre origine. Le code d'une iframe cross-origin ne peut pas appeler directement une fonction de la page parente : il ne peut donc pas simplement appeler __tcfapi ou __gpp et lire le choix du visiteur.

Les cadres de l'IAB résolvent ce problème par une convention de messagerie petite et bien définie. Si vous créez des produits publicitaires, des intégrations ou des scripts de mesure qui s'exécutent dans des frames, ou si vous déboguez des piles publicitaires qui le font, il vaut la peine de savoir exactement comment elle fonctionne.

La frame locator

En plus de l'API JavaScript, un CMP TCF ajoute à la page de niveau supérieur une iframe vide et invisible nommée __tcfapiLocator. Un CMP GPP fait de même avec une frame nommée __gppLocator. Ces frames ne contiennent rien. Leur seul rôle est d'être repérables : tout script de n'importe quelle frame imbriquée peut remonter la hiérarchie des fenêtres et vérifier à chaque niveau si une frame portant ce nom existe.

Comme les noms de frames sont visibles entre origines via window.frames, un script placé dans une iframe cross-origin profondément imbriquée peut localiser la fenêtre qui héberge le CMP sans avoir accès à quoi que ce soit d'autre sur cette page.

Comment un script encadré trouve le CMP

  1. Commencez par la fenêtre courante. Si __tcfapi existe localement, utilisez-le directement — le script n'est pas dans une frame, ou la frame partage le CMP.
  2. Sinon, remontez en boucle : vérifiez si la fenêtre courante contient une frame nommée __tcfapiLocator ; si ce n'est pas le cas, passez à window.parent et vérifiez à nouveau, en vous arrêtant à la fenêtre de niveau supérieur.
  3. Lorsque la frame locator est trouvée, la fenêtre qui la contient est la fenêtre du CMP. La communication passe alors par postMessage.

Enveloppez chaque accès dans un try/catch, car certains navigateurs ou réglages de sandboxing lèvent une exception lors d'un accès cross-origin à une propriété, et arrêtez la boucle lorsque window.parent est égal à la fenêtre courante.

Le format des messages

Pour le TCF, le script encadré envoie à la fenêtre du CMP un message contenant un objet doté d'une propriété __tcfapiCall. Elle renferme quatre champs :

Le CMP écoute ces messages, exécute la commande et renvoie un objet doté d'une propriété __tcfapiReturn contenant returnValue, success et le même callId. L'appelant conserve une table des callbacks en attente indexée par callId, écoute les événements message et achemine chaque retour vers le bon callback. Le GPP suit le même schéma avec __gppCall et __gppReturn.

De nombreuses intégrations écrivent un petit proxy : une fonction locale nommée __tcfapi dans la frame, qui traduit les appels en messages. Le code écrit pour la fenêtre de niveau supérieur fonctionne alors sans modification dans la frame.

Les listeners d'événements entre frames

Un appel addEventListener envoyé par postMessage n'est pas une requête ponctuelle. Le CMP renverra un message de retour chaque fois que l'état du consentement change, tous avec le même callId. Votre dispatcher doit donc conserver ce callback enregistré au lieu de le supprimer après la première réponse. L'oublier est un bogue classique : le script encadré lit le consentement une fois et ne remarque jamais un retrait ultérieur.

Considérations de sécurité

Là où le schéma ne porte pas

Certains environnements publicitaires isolent plus strictement les créations. Les conteneurs SafeFrame, les iframes en sandbox sans les bonnes permissions et les créations rendues dans des documents séparés peuvent ne pas pouvoir parcourir l'arbre des frames ni recevoir de messages. Dans ces cas, le signal de consentement doit généralement être transmis explicitement, par exemple sous forme de paramètres de la requête publicitaire ou de valeurs remises à la création par l'ad server, comme les paramètres gdpr et gdpr_consent que prennent en charge de nombreuses balises publicitaires.

Checklist de débogage

À retenir

← Blog Tout lire →