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
- 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.
- 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.
- 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:
- command — por exemplo getTCData, ping ou addEventListener;
- parameter — qualquer argumento de que o comando precise, ou null;
- version — a versão da API, 2 para o TCF v2;
- callId — um valor único gerado por quem chama.
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
- Valide o formato da mensagem. Ignore qualquer mensagem que não contenha a propriedade esperada e analise com cuidado payloads de tipo string, pois algumas implementações enviam strings JSON em vez de objetos.
- Não confie às cegas. Qualquer página pode enviar mensagens ao seu frame. Trate as respostas como sinais de consentimento a respeitar, não como dados autenticados, e nunca deixe que disparem ações privilegiadas.
- Use origens de destino específicas sempre que puder. Quando a origem do CMP é conhecida, envie a mensagem a ela em vez de a todas as origens.
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
- No DevTools da janela de nível superior, confirme que os frames locator existem no painel Elements.
- Troque o contexto do console para o iframe e verifique se o locator está acessível a partir dele.
- Registre em log os eventos message recebidos nas duas janelas para confirmar que chamadas e retornos estão fluindo.
- Altere o consentimento no banner e verifique se os listeners nos frames recebem uma atualização.
- Teste com o CMP carregado tarde, para garantir que o código em frame tente de novo ou espere em vez de desistir de imediato.
Principais conclusões
- Frames cross-origin alcançam o CMP por meio dos frames __tcfapiLocator e __gppLocator.
- Chamadas e retornos usam postMessage com __tcfapiCall/__tcfapiReturn ou os equivalentes do GPP, pareados por callId.
- Mantenha registrados os callbacks dos listeners para que as mudanças de consentimento posteriores cheguem.
- Valide cada mensagem e evite tratá-la como entrada confiável.
- Onde os frames são totalmente isolados, repasse o consentimento explicitamente na requisição de anúncio.