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
- 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.
- 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.
- 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 :
- command — par exemple getTCData, ping ou addEventListener ;
- parameter — tout argument dont la commande a besoin, ou null ;
- version — la version de l'API, 2 pour TCF v2 ;
- callId — une valeur unique générée par l'appelant.
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é
- Validez la forme des messages. Ignorez tout message qui ne contient pas la propriété attendue, et analysez les charges utiles de type chaîne avec prudence, car certaines implémentations envoient des chaînes JSON plutôt que des objets.
- Ne faites pas confiance aveuglément. N'importe quelle page peut envoyer des messages à votre frame. Traitez les réponses comme des signaux de consentement à respecter, non comme des données authentifiées, et ne les laissez jamais déclencher d'actions privilégiées.
- Utilisez des origines cibles précises lorsque vous le pouvez. Quand l'origine du CMP est connue, envoyez le message à cette origine plutôt qu'à toutes.
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
- Dans les DevTools de la fenêtre de niveau supérieur, confirmez que les frames locator existent dans le panneau Elements.
- Basculez le contexte de la console vers l'iframe et vérifiez si la frame locator y est accessible.
- Journalisez les événements message entrants dans les deux fenêtres pour confirmer que les appels et les retours circulent.
- Modifiez le consentement dans la bannière et vérifiez que les listeners encadrés reçoivent une mise à jour.
- Testez avec un CMP chargé tardivement, pour vous assurer que le code encadré réessaie ou attend au lieu d'abandonner immédiatement.
À retenir
- Les frames cross-origin atteignent le CMP via les frames __tcfapiLocator et __gppLocator.
- Les appels et les retours utilisent postMessage avec __tcfapiCall/__tcfapiReturn ou les équivalents GPP, appariés par callId.
- Gardez les callbacks de listeners enregistrés pour que les changements de consentement ultérieurs parviennent.
- Validez chaque message et évitez de le traiter comme une entrée de confiance.
- Lorsque les frames sont totalement isolées, transmettez le consentement explicitement dans la requête publicitaire.