O que é um iframe e por que é difícil de rastrear?
Um iframe (inline frame) é um elemento HTML que incorpora conteúdo de outra página dentro da página principal. Plataformas populares como YouTube, Google Maps, Calendly e formulários de terceiros são frequentemente incorporados como iframes.
O problema é que ações dentro de iframes ficam isoladas da janela principal — o GTM instalado na página pai não consegue ver diretamente o que acontece dentro do iframe. Isso cria um gap no rastreamento.
Como detectar iframes no código
- Clique com o botão direito no elemento que quer rastrear e selecione 'Inspecionar'
- No painel de código, procure pela tag `
- Anote o domínio da fonte do iframe (atributo `src`) para identificar se é same-domain ou cross-domain
- Verifique se há múltiplos iframes na página — cada um pode exigir abordagem diferente
Se o iframe é de um domínio diferente (cross-domain), você terá limitações adicionais de segurança do navegador (política de mesma origem). Isso restringe as técnicas disponíveis.
Como rastrear eventos dentro do iframe
Opção 1: Web APIs da plataforma
Muitas plataformas (YouTube, Google Maps, Calendly) oferecem Web APIs JavaScript que funcionam diretamente na janela pai, sem precisar de acesso ao código dentro do iframe. Essa é a abordagem mais simples e confiável.
Opção 2: Instalar GTM dentro do iframe
Se você tem controle sobre o conteúdo do iframe (mesmo domínio ou acesso ao código), pode instalar um container GTM dentro do iframe. Isso permite configurar eventos de forma flexível.
Opção 3: window.postMessage()
Para iframes de terceiros sem Web API, use `window.postMessage()` para enviar dados do iframe para a janela pai. O iframe envia mensagens e a janela pai as escuta com um listener.
- Configure um listener no GTM da janela pai para receber mensagens do iframe
- O iframe (se você tiver acesso) envia dados usando `window.parent.postMessage(data, '*')`
- O listener na janela pai captura a mensagem e empurra um evento ao dataLayer
- Configure a tag GTM para disparar com base nesse evento do dataLayer
Se você não pode instalar GTM no iframe E o iframe não tem Web API E é cross-domain sem controle do código — o rastreamento provavelmente não é possível sem modificar o iframe na origem.
Configuração completa passo a passo
- Verifique a presença do iframe inspecionando o código da página
- Identifique o domínio fonte (same-domain ou cross-domain)
- Para plataformas com Web API (YouTube, Calendly): configure o listener na janela pai usando a API oficial
- Para iframes próprios: adicione o snippet do GTM dentro do iframe ou use postMessage
- Configure triggers de exceção no GTM para evitar que tags disparem dentro do iframe indevidamente
- Teste o fluxo completo no Preview Mode do GTM e valide no GA4 DebugView
Perguntas frequentes
Posso rastrear eventos no Calendly incorporado?
Sim. O Calendly oferece uma Web API chamada 'Calendly Events' que emite eventos JavaScript quando o usuário interage com o widget. Use esses eventos no GTM da página pai sem precisar acessar o iframe.
O YouTube iframe tem API para rastreamento?
Sim. A YouTube Player API permite detectar eventos como play, pause, fim de vídeo e progresso. Configure um listener GTM usando a IFrame Player API do YouTube na janela pai.
Por que meu tag GTM está disparando dentro do iframe?
Isso acontece quando a tag usa um trigger sem filtro de contexto. Adicione uma exceção ao trigger usando a variável `isFrame` ou verifique se `window.self === window.top` para garantir que a tag só dispara na janela principal.
Este artigo é uma adaptação em português de conteúdo originalmente publicado em inglês pela equipe da Stape. Ver artigo original.