AGENT SKILL

gtm-implementation

Gtm Implementation — Skill especializada para gtm implementation

License 许可
MIT
最近更新
2026-08-01
Stars
★ 2
Forks
0

01 前言 Front Matter

name
gtm-implementation
risk
safe
license
MIT
metadata
{ "author": "Cafe Code AI", "updated": 1772323200000, "version": "1.0.0", "category": "15-analytics-dados" }
description
Gtm Implementation — Skill especializada para gtm implementation

03 SKILL.md 正文

Gtm Implementation

Esta skill capacita o Claude a projetar, implementar e depurar configurações de Google Tag Manager (GTM) para coleta de dados robusta e precisa no Google Analytics 4 (GA4), otimizando a rastreabilidade e a qualidade das informações.


Keywords

GTM, GA4, Data Layer, Tags, Triggers, Variables, Consent Mode v2, Enhanced Measurement, Event Tracking, Custom Events, Debug View, RegEx Table, Server-Side GTM, User-ID.


Quick Start

  1. Criar Container GTM: Acesse tagmanager.google.com, clique em "Criar Conta", nomeie a conta e o container (ex: "Nome da Empresa - Web"), selecione "Web" como plataforma.
  2. Instalar Código Base GTM: Copie os dois snippets de código GTM fornecidos (um para <head> e outro para <body>) e insira-os nas respectivas seções de todas as páginas do site a ser rastreado.
  3. Configurar Tag de Configuração GA4: No GTM, crie uma nova "Tag", selecione "Configuração do Google Analytics: Evento GA4", insira o ID de Medição do GA4 (ex: G-XXXXXXXXXX) e configure-a para disparar em "Todas as Páginas".
  4. Publicar Primeira Versão: Clique em "Enviar" no GTM, nomeie a versão (ex: "Configuração Inicial GA4") e adicione uma descrição. Em seguida, clique em "Publicar".
  5. Verificar com Debug View: Abra o site em uma nova aba do navegador com o gtm_debug=x na URL ou use a extensão GTM/GA4 Debugger. No GA4, navegue até "Administrador" > "DebugView" para confirmar a chegada dos eventos de page_view e de configuração.

Core Workflows

Workflow 1: Implementação de Evento Personalizado para Cliques em Botões Específicos (GA4 via GTM)

Este workflow detalha a captura de cliques em um botão específico e o envio como um evento personalizado para o GA4, incluindo parâmetros relevantes.

Cenário: Rastreador de cliques no botão "Agendar Consulta" em uma página de serviço.

Passos Detalhados:

  1. Identificar o Seletor CSS do Elemento:

    • No navegador, inspecione o botão "Agendar Consulta".
    • Encontre um seletor CSS único. Exemplo: button.btn-primary.btn-agendar ou a[data-event="agendar-consulta"].
    • Se não houver um seletor único, peça ao desenvolvedor para adicionar um id ou data-attribute (ex: id="btnAgendarConsulta").
  2. Habilitar Variáveis de Cliques no GTM:

    • No GTM, vá em "Variáveis" > "Variáveis Integradas" > "Configurar".
    • Habilite todas as variáveis na seção "Cliques" (Click ID, Click Classes, Click Element, Click Target, Click URL, Click Text).
  3. Criar Variável para Capturar Texto do Botão (Opcional, mas recomendado):

    • No GTM, vá em "Variáveis" > "Variáveis Definidas pelo Usuário" > "Nova".
    • Tipo: "Variável de Elemento de Clique".
    • Nome: {{Click Text}} (se habilitada) ou crie uma "Variável DOM" se precisar de um atributo específico.
    • Exemplo: {{Click Text}} já é uma variável integrada que captura o texto do elemento clicado.
  4. Criar Disparador (Trigger) de Cliques Específicos:

    • No GTM, vá em "Acionadores" > "Novo".
    • Tipo de Acionador: "Clique - Apenas Links" ou "Clique - Todos os Elementos" (dependendo do elemento). Para botões, "Todos os Elementos" é mais seguro.
    • Nome: Click - Botão Agendar Consulta
    • Condição: "Alguns cliques".
    • Defina a condição com base no seletor CSS ou ID:
      • Click Element > matches CSS selector > button.btn-primary.btn-agendar
      • OU Click ID > equals > btnAgendarConsulta
      • OU Click Text > equals > Agendar Consulta
    • Certifique-se de que o trigger seja suficientemente específico para evitar falsos positivos.
  5. Criar Tag de Evento GA4 Personalizado:

    • No GTM, vá em "Tags" > "Nova".
    • Tipo de Tag: "Google Analytics: Evento GA4".
    • Nome: GA4 Event - Click Agendar Consulta
    • Tag de Configuração: Selecione a tag de configuração GA4 já criada (ex: GA4 Config - Todas as Páginas).
    • Nome do Evento: agendar_consulta (padrão snake_case recomendado pelo GA4).
    • Parâmetros do Evento (Opcional, mas útil):
      • event_category: interacao
      • event_label: {{Click Text}} (para capturar o texto do botão clicado)
      • page_path: {{Page Path}} (para saber em qual página ocorreu o clique)
    • Acionamento: Selecione o trigger Click - Botão Agendar Consulta criado no passo 4.
  6. Testar e Publicar:

    • Abra o GTM em "Visualizar", insira a URL do site.
    • Navegue até a página com o botão "Agendar Consulta".
    • Clique no botão.
    • No painel de depuração do GTM (Tag Assistant), verifique se a tag GA4 Event - Click Agendar Consulta foi disparada e se os parâmetros estão corretos.
    • No GA4 DebugView, confirme que o evento agendar_consulta chegou com os parâmetros esperados.
    • Após a validação, clique em "Enviar" no GTM para publicar a nova versão do container.

Workflow 2: Configuração de Modo de Consentimento (Consent Mode v2) no GA4 via GTM

Este workflow descreve a implementação do Consent Mode v2 do Google para garantir a conformidade com regulamentações de privacidade, ajustando o comportamento das tags GA4 com base no consentimento do usuário.

Cenário: Implementar Consent Mode v2 para um site usando um banner de consentimento (CMP - Consent Management Platform) e ajustar as tags GA4.

Passos Detalhados:

  1. Escolher e Implementar a CMP:

    • Selecione uma CMP que suporte o Google Consent Mode v2 (ex: OneTrust, Cookiebot, Usercentrics, ou uma solução customizada).
    • Implemente o script da CMP no <head> do seu site, antes do código GTM. A CMP deve definir as variáveis de consentimento do Google (gtag('consent', 'update', { ... })) ou integrar-se diretamente com o GTM.
  2. Configurar Tag de Inicialização de Consentimento GTM (se a CMP não fizer isso):

    • No GTM, vá em "Tags" > "Nova".
    • Tipo de Tag: "HTML Personalizado".
    • Nome: HTML - Consent Mode Default
    • Código HTML:
      <script>
        window.dataLayer = window.dataLayer || [];
        function gtag(){dataLayer.push(arguments);}
        gtag('consent', 'default', {
          'ad_storage': 'denied',
          'analytics_storage': 'denied',
          'ad_user_data': 'denied',
          'ad_personalization': 'denied',
          'wait_for_update': 500
        });
        gtag('set', 'ads_data_redaction', true); // Reduzir dados de anúncios
        gtag('set', 'url_passthrough', true); // Passagem de URL (para cliques)
      </script>
      
    • Acionamento: "Inicialização de Consentimento - Todas as Páginas". Este é o primeiro trigger a ser disparado e define o estado padrão do consentimento.
  3. Configurar Tag de Atualização de Consentimento (se a CMP não usar o Data Layer):

    • Se sua CMP não envia atualizações de consentimento via dataLayer.push, você precisará criar uma tag HTML personalizada para isso, disparada por um evento customizado da CMP.
    • Exemplo com Data Layer push da CMP: A CMP envia um dataLayer.push como window.dataLayer.push({'event': 'consent_updated', 'consent_status': {...}}) quando o usuário toma uma decisão.
    • No GTM, vá em "Tags" > "Nova".
    • Tipo de Tag: "HTML Personalizado".
    • Nome: HTML - Consent Mode Update
    • Código HTML (exemplo, adaptado à sua CMP):
      <script>
        // Este script é um exemplo. Sua CMP deve injetar o consentimento diretamente.
        // Se a CMP expõe um objeto global com o estado do consentimento:
        // var consentState = window.myCmp.getConsentState();
        // gtag('consent', 'update', {
        //   'ad_storage': consentState.ad_storage ? 'granted' : 'denied',
        //   'analytics_storage': consentState.analytics_storage ? 'granted' : 'denied'
        // });
      </script>
      
    • Acionamento: Crie um "Acionador de Evento Personalizado" para o evento que sua CMP dispara (ex: consent_updated).
  4. Ajustar Configurações de Tag GA4 para Consentimento:

    • Vá para sua Tag de Configuração GA4 (ex: GA4 Config - Todas as Páginas).
    • Em "Configurações avançadas", marque "Habilitar configuração de consentimento" e "Requer consentimento adicional para disparar a tag".
    • Adicione as seguintes verificações de consentimento:
      • ad_storage: Não é necessário consentimento adicional (ou Ad_storage se sua CMP gerencia isso via dataLayer)
      • analytics_storage: analytics_storage (para a tag disparar apenas com consentimento de analytics)
    • Faça o mesmo para todas as outras tags GA4 (Eventos, E-commerce, etc.), configurando analytics_storage como analytics_storage para as tags de analytics e ad_storage para tags de publicidade.
  5. Testar e Publicar:

    • Abra o GTM em "Visualizar".
    • No seu site, observe o banner de consentimento.
    • Cenário 1: Negar tudo: No Tag Assistant, a tag HTML - Consent Mode Default deve disparar e as tags GA4 não devem disparar ou devem disparar em modo restrito (sem cookies). No GA4 DebugView, você deve ver dados modelados ou limitados, e nenhum cookie GA4 deve ser definido.
    • Cenário 2: Aceitar tudo: Após o consentimento, a tag de atualização do consentimento deve disparar, e as tags GA4 devem disparar normalmente, definindo cookies. No GA4 DebugView, os dados devem aparecer completos.
    • Após a validação, clique em "Enviar" no GTM para publicar a nova versão do container.

Templates

Estrutura de Data Layer Push para Evento de Compra (GA4 e GTM)

Este template demonstra como estruturar um dataLayer.push para um evento de compra, seguindo o esquema de e-commerce do GA4, essencial para a coleta de dados de transações.

<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: "purchase",
    ecommerce: {
      transaction_id: "T_20240301-123456", // ID único da transação
      value: 125.99, // Valor total da compra
      currency: "BRL", // Moeda
      tax: 15.00, // Imposto
      shipping: 5.00, // Custo de envio
      coupon: "FRETEGRATIS2024", // Cupom utilizado
      items: [
        {
          item_id: "SKU7890",
          item_name: "Camiseta Premium Algodão",
          affiliation: "Loja Virtual",
          coupon: "DESCONTO10",
          currency: "BRL",
          item_brand: "Marca X",
          item_category: "Vestuário",
          item_category2: "Camisetas",
          item_variant: "Azul - M",
          price: 59.99,
          quantity: 1
        },
        {
          item_id: "SKU1234",
          item_name: "Calça Jeans Slim Fit",
          affiliation: "Loja Virtual",
          coupon: "DESCONTO10",
          currency: "BRL",
          item_brand: "Marca Y",
          item_category: "Vestuário",
          item_category2: "Calças",
          item_variant: "Preto - 40",
          price: 60.00,
          quantity: 1
        }
      ]
    }
  });
</script>

Configuração de Variável de Regex Table para Categorização de Conteúdo (GA4 e GTM)

Este template ilustra como usar uma variável RegEx Table no GTM para categorizar URLs de páginas em grupos de conteúdo, útil para relatórios no GA4.

Variável GTM: Content Grouping
Tipo: Tabela de Expressão Regular
Variável de Entrada: {{Page Path}}

Tabela de Mapeamento:
  - Padrão de Expressão Regular: ^/blog(/.*)?$
    Valor de Saída: Blog
  - Padrão de Expressão Regular: ^/servicos(/.*)?$
    Valor de Saída: Serviços
  - Padrão de Expressão Regular: ^/produtos(/.*)?$
    Valor de Saída: Produtos
  - Padrão de Expressão Regular: ^/contato$
    Valor de Saída: Contato
  - Padrão de Expressão Regular: ^/$
    Valor de Saída: Página Inicial
  - Padrão de Expressão Regular: .* // Padrão catch-all para categorizar o restante
    Valor de Saída: Outros

Uso: Esta variável {{Content Grouping}} pode ser adicionada como um parâmetro personalizado em suas tags de evento GA4 (incluindo a tag de configuração), por exemplo, como content_group ou page_category.


Checklist

  • [x] O container GTM está instalado corretamente no <head> e <body> de todas as páginas do site?
  • [x] O dataLayer está inicializado antes do script GTM em todas as páginas? (window.dataLayer = window.dataLayer || [];)
  • [x] A Tag de Configuração GA4 (ID de Medição G-XXXXXXXXXX) está configurada para disparar em "Todas as Páginas"?
  • [x] Todas as tags de evento GA4 personalizadas possuem um "Nome do Evento" em snake_case (ex: add_to_cart) e parâmetros relevantes?
  • [x] As variáveis de Data Layer ou DOM estão configuradas para extrair os valores corretos (verificado no modo "Visualizar" do GTM)?
  • [x] Os triggers de evento (clique, formulário, etc.) são específicos o suficiente para evitar disparos indesejados (usando CSS Selectors, IDs, URLs)?
  • [x] O Consent Mode v2 está implementado e a tag de inicialização de consentimento (se usada) dispara na "Inicialização de Consentimento - Todas as Páginas"?
  • [x] As tags GA4 estão configuradas para respeitar o consentimento (analytics_storage e ad_storage) nas "Configurações Avançadas > Configurações de Consentimento"?
  • [x] Eventos de Enhanced Measurement do GA4 (ex: cliques em links, download) estão desabilitados no GA4 se forem duplicados por tags GTM personalizadas?
  • [x] Todas as novas implementações foram testadas no modo "Visualizar" do GTM e no "DebugView" do GA4 antes da publicação?
  • [x] As versões do GTM são nomeadas e possuem descrições claras para facilitar o histórico de alterações?
  • [x] Existem tags de remoção ou exceção configuradas para evitar o disparo de tags em ambientes de desenvolvimento ou staging?

Métricas de Referência

Métrica Benchmark Meta
Taxa de Acerto de Eventos (GTM Debugger/GA4 DebugView) >98% (eventos esperados) 100% (eventos esperados)
Latência de Dados (GA4 Realtime Report) <30 segundos <10 segundos
Discrepância de Dados (GA4 vs. Fonte de Verdade) <5% <1%
Coleta de Consentimento (GA4 - consent_status eventos) >80% (Analytics/Ads) >90% (Analytics/Ads)
Erros de Configuração de Tags (Ferramentas de Auditoria) 0 0
Tempo de Carregamento da Página (impacto GTM) <100ms <50ms

Erros Comuns

  1. Data Layer não inicializado ou inicializado tarde: Se window.dataLayer = window.dataLayer || []; não estiver no <head> antes do script GTM, ou se eventos forem enviados antes da inicialização, os dados podem ser perdidos.
    • Como evitar: Sempre coloque window.dataLayer = window.dataLayer || []; como a primeira linha do <head> do seu site, antes de qualquer outro script, incluindo o próprio GTM. Garanta que todos os dataLayer.push ocorram após esta inicialização.
  2. Triggers de cliques muito genéricos: Usar um trigger "Clique - Todos os Elementos" com uma condição Click URL contains / para um evento específico pode causar disparos em elementos indesejados, resultando em dados inflacionados e imprecisos.
    • Como evitar: Utilize seletores CSS (Click Element matches CSS selector .minha-classe-de-botao), IDs (Click ID equals meuBotaoUnico) ou atributos de dados (Click Element matches CSS selector [data-event="meu-evento"]) para tornar os triggers de clique o mais específico possível.
  3. Variáveis de Data Layer ou DOM configuradas incorretamente: Erros na chave de Data Layer (ex: ecommerce.purchase.value em vez de ecommerce.value) ou seletores CSS errados para variáveis DOM resultam em valores undefined ou nulos no GA4.
    • Como evitar: Use o modo "Visualizar" do GTM para inspecionar os valores das variáveis em tempo real. Para variáveis de Data Layer, use o console do navegador (dataLayer) para verificar a estrutura exata do objeto. Para variáveis DOM, teste o seletor CSS no console (document.querySelector('.minha-classe').innerText) antes de configurar no GTM.
  4. Duplicação de eventos de Medição Aprimorada (Enhanced Measurement) do GA4: O GA4 coleta automaticamente eventos como click (links externos), file_download, scroll, video_start, etc. Se você criar tags GTM personalizadas para esses mesmos eventos, eles serão enviados duas vezes.
    • Como evitar: No painel de administração do GA4, vá em "Fluxos de dados" > "Web" > "Detalhes do fluxo" e desabilite os eventos de Medição Aprimorada que você implementa manualmente via GTM. Por exemplo, se você tem uma tag GTM para file_download, desative o "Downloads de arquivos" na Medição Aprimorada.

Dicas Avançadas

  1. Utilização de Variáveis de Regex Table para Content Grouping Dinâmico: Em vez de configurar grupos de conteúdo manualmente no GA4, use uma variável RegEx Table no GTM para mapear URLs ({{Page Path}}) para categorias de conteúdo. Adicione esta variável como um parâmetro de evento (content_group) à sua tag de configuração GA4 e a todas as tags de evento para categorização automática. Isso simplifica a gestão e garante consistência nos relatórios.
  2. Implementação de User-ID Persistente via Variável de Armazenamento Personalizado: Para rastrear usuários logados de forma consistente em diferentes sessões e dispositivos, crie uma variável GTM do tipo "Armazenamento Personalizado" (Custom JavaScript) que capture o User-ID do dataLayer e o salve em um cookie ou localStorage. Use essa variável para configurar o campo user_id nas tags GA4 quando um usuário estiver logado.
  3. Configuração de Server-Side GTM para Maior Controle e Resiliência: Para cenários onde a privacidade, a performance e a resiliência dos dados são críticas, considere a migração para o Google Tag Manager Server-Side. Isso permite que você mova a lógica de processamento de tags para um servidor em nuvem que você controla, reduzindo a carga no navegador do usuário, contornando bloqueadores de anúncios (em certos casos) e aumentando a segurança dos dados.
  4. Automação de Testes de GTM com Cypress ou Selenium: Para grandes implementações ou sites com atualizações frequentes, desenvolver scripts de teste automatizados usando ferramentas como Cypress ou Selenium para simular interações do usuário e verificar o disparo correto das tags no dataLayer é crucial. Isso garante que as implementações GTM permaneçam funcionais e precisas após cada deploy.
  5. Gerenciamento de Multi-Ambientes (Dev, Staging, Prod) com Variáveis Look-up Table: Evite a necessidade de criar containers GTM separados para cada ambiente. Utilize uma variável do tipo "Tabela de Pesquisa" (Look-up Table) no GTM. A variável de entrada pode ser {{Page Hostname}}. Mapeie o hostname de cada ambiente (ex: dev.meusite.com, staging.meusite.com, www.meusite.com) para diferentes IDs de Medição do GA4 ou IDs de contêiner GTM, permitindo que o mesmo container GTM se adapte ao ambiente.

04 同仓库更多 Skills