Consentimento dentro de iframes cross-origin: o padrão __tcfapiLocator e __gppLocator

O problema: o consentimento vive na janela principal

Um CMP roda na sua página, na janela de nível superior. Grande parte da sua publicidade, não. Criativos display, rich media, renderizadores de header bidding e muitos widgets de terceiros rodam dentro de iframes, muitas vezes em outra origem. O código em um iframe cross-origin não consegue chamar diretamente uma função da página pai, então não pode simplesmente chamar __tcfapi ou __gpp e ler a escolha do visitante.

Os frameworks do IAB resolvem isso com uma convenção de mensagens pequena e bem definida. Se você cria produtos de anúncios, embeds ou scripts de medição que rodam em frames, ou depura stacks de anúncios que fazem isso, vale saber exatamente como ela funciona.

O frame locator

Além da API JavaScript, um CMP TCF adiciona à página de nível superior um iframe vazio e invisível chamado __tcfapiLocator. Um CMP GPP faz o mesmo com um frame chamado __gppLocator. Os frames não têm conteúdo. A única função deles é poder ser encontrados: qualquer script em qualquer frame aninhado pode subir pela hierarquia de janelas e verificar, em cada nível, se existe um frame com esse nome.

Como os nomes dos frames são visíveis entre origens por meio de window.frames, um script em um iframe cross-origin profundamente aninhado consegue localizar a janela que hospeda o CMP sem ter acesso a mais nada naquela página.

Como um script em frame encontra o CMP

  1. Comece pela janela atual. Se __tcfapi existir localmente, use-o diretamente — o script não está em um frame, ou o frame compartilha o CMP.
  2. Caso contrário, suba em loop: verifique se a janela atual contém um frame chamado __tcfapiLocator; se não, passe para window.parent e verifique de novo, parando na janela de nível superior.
  3. Quando o locator é encontrado, a janela que o contém é a janela do CMP. A comunicação passa então a ocorrer por postMessage.

Envolva cada acesso em um try/catch, porque alguns navegadores ou configurações de sandbox lançam uma exceção no acesso cross-origin a propriedades, e interrompa o loop quando window.parent for igual à janela atual.

O formato da mensagem

Para o TCF, o script em frame envia à janela do CMP uma mensagem contendo um objeto com uma propriedade __tcfapiCall. Dentro dela há quatro campos:

O CMP escuta essas mensagens, executa o comando e devolve um objeto com uma propriedade __tcfapiReturn contendo returnValue, success e o mesmo callId. Quem chama mantém um mapa de callbacks pendentes indexado por callId, escuta os eventos message e despacha cada retorno para o callback certo. O GPP segue o mesmo padrão com __gppCall e __gppReturn.

Muitas integrações escrevem um pequeno proxy: uma função local chamada __tcfapi dentro do frame que traduz as chamadas em mensagens. O código escrito para a janela de nível superior passa então a funcionar sem alterações dentro do frame.

Listeners de eventos entre frames

Uma chamada addEventListener enviada por postMessage não é uma requisição única. O CMP enviará uma mensagem de retorno toda vez que o estado de consentimento mudar, todas com o mesmo callId. Seu dispatcher deve, portanto, manter esse callback registrado em vez de excluí-lo após a primeira resposta. Esquecer isso é um bug clássico: o script em frame lê o consentimento uma vez e nunca percebe uma retirada posterior.

Considerações de segurança

Onde o padrão não chega

Alguns ambientes de anúncios isolam os criativos de forma mais rígida. Contêineres SafeFrame, iframes em sandbox sem as permissões certas e criativos renderizados em documentos separados podem não conseguir percorrer a árvore de frames nem receber mensagens. Nesses casos, o sinal de consentimento normalmente precisa ser repassado explicitamente, por exemplo como parâmetros da requisição de anúncio ou como valores entregues ao criativo pelo ad server, como os parâmetros gdpr e gdpr_consent que muitas tags de anúncios aceitam.

Checklist de depuração

Principais conclusões

← Blog Ler tudo →