Quase toda implementação de GA4 começa bem: page_view, scroll, cliques de saída e, em lojas, os eventos recomendados de e-commerce. O problema aparece quando alguém pede para medir algo que o Google não previu, como o clique no botão de WhatsApp, o frete escolhido ou o cupom aplicado. Surge então um evento novo, com nome improvisado, e semanas depois o relatório não mostra o parâmetro que todos achavam estar sendo coletado.
Este guia explica como criar eventos personalizados e parâmetros no GA4 de forma que os dados cheguem, sejam legíveis e não estourem limites. Você vai ver a diferença entre os tipos de evento, as regras de nomenclatura, os limites da propriedade, o caminho do gtag e do GTM, a função Criar evento na interface, o registro de dimensões e métricas personalizadas e a validação no DebugView. Todos os limites vêm da documentação oficial do Google.
Uma nota de método: onde a documentação não confirma um detalhe, o texto diz isso. Exemplos numéricos são hipotéticos. Nomes de eventos e parâmetros usados nos exemplos são sugestões da Analytikos.
Tipos de evento: quando um evento deve ser personalizado
A página sobre tipos de evento no GA4 separa quatro grupos. Escolher o grupo certo evita criar evento personalizado onde já existe um recomendado.
| Tipo | Quem define o nome | Quando usar |
|---|---|---|
| Automático | O Google | Coletado assim que o GA4 é configurado, como page_view e session_start |
| Medição otimizada | O Google | Coletado quando a medição otimizada está ligada no fluxo de dados |
| Recomendado | O Google define nome e parâmetros; você implementa | Quando o caso está previsto, como e-commerce; garante compatibilidade com recursos atuais e futuros |
| Personalizado | Você | Só quando nenhum outro tipo atende; em geral não aparece nos relatórios padrão e exige explorações ou relatórios personalizados |
A regra prática: se o evento existe na lista de recomendados, como os de e-commerce no GA4, use o nome do Google. Crie evento personalizado apenas para o que é específico do seu negócio.
Regras de nomenclatura
Segundo as regras de nomenclatura de eventos, os nomes diferenciam maiúsculas de minúsculas, precisam começar com uma letra e aceitam letras, números e sublinhados, sem espaços. A lista de nomes reservados não é completa e pode mudar, e o GA mostra erro ao usar um reservado. Entre os nomes reservados na web, a página cita app_remove, file_download, first_visit, form_start, form_submit, page_view, scroll, session_start, user_engagement, video_progress, video_start e view_search_results.
- Prefixos reservados em nomes de parâmetro: sublinhado inicial, firebase_, ga_, google_ e gtag.
- Parâmetros reservados para dimensões e métricas personalizadas incluem cid, currency, customer_id, dclid, gclid, session_id, sid, srsltid, uid e user_id.
- Nome de evento e nome de parâmetro aceitam até 40 caracteres.
- click_whatsapp e Click_Whatsapp são eventos diferentes, porque o nome diferencia caixa.
A recomendação da Analytikos é adotar snake_case em minúsculas, com verbo no começo ou substantivo e ação, como click_whatsapp, filter_apply e coupon_apply, e documentar tudo num plano de medição. Um nome com letra maiúscula ou acento digitado diferente por outro desenvolvedor vira outro evento e divide os dados.
Limites que determinam o desenho do plano
A página de limites de coleta e configuração define os números abaixo para propriedades padrão. Uma correção importante em relação a materiais antigos: segundo a página, não há limite para a quantidade de nomes de evento distintos em fluxos de dados web; o limite de 500 vale para fluxos de app. Confira a página oficial antes de planejar, porque limites mudam.
| Item | Limite (propriedade padrão) |
|---|---|
| Caracteres no nome do evento | 40 |
| Parâmetros por evento | 25 |
| Caracteres no nome do parâmetro | 40 |
| Caracteres no valor do parâmetro | 100 (exceções: page_title 300, page_referrer 420, page_location 1.000) |
| Propriedades de usuário | 25 (nome com até 24 caracteres e valor com até 36) |
| Eventos por usuário por dia | 100.000 |
| Dimensões personalizadas de evento | 50 |
| Dimensões personalizadas de usuário | 25 |
| Dimensões personalizadas de item | 10 |
| Métricas personalizadas | 50 |
| Métricas calculadas | 5 |
O GA 360 amplia a maioria desses limites, exceto os de caracteres. Para economizar cota, a documentação sugere priorizar dimensões predefinidas e remover registros duplicados.
Como enviar um evento personalizado
Pelo gtag.js
A página do Google for Developers sobre envio de eventos com gtag.js mostra a sintaxe gtag(‘event’, nome, parâmetros). O evento precisa vir abaixo do snippet da tag do Google; acima dele, não é processado.
gtag('event', 'click_whatsapp', {
click_location: 'pdp',
page_type: 'produto'
});Pelo GTM com dataLayer
No Google Tag Manager, a tag de evento GA4 tem ID de métricas, nome do evento e parâmetros opcionais, como descreve a ajuda da tag de evento do GA4. Um nome personalizado cria um evento personalizado, e um nome predefinido cria um recomendado. Para eventos de interface, o padrão é o site empurrar um objeto para a camada de dados e o GTM disparar a tag.
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'payment_method_select',
payment_method: 'pix',
installments: 1
});A documentação da camada de dados traz três cuidados: não sobrescrever a variável dataLayer, usar nomes de chave consistentes entre páginas, porque a caixa importa, e lembrar que a ordem das mensagens importa. A tag, o acionador e as variáveis estão no guia de GTM para iniciantes, e a construção confiável da camada de dados está em dataLayer no GTM.
Pela interface: Criar evento e Modificar evento
Em Administrador, Exibição de dados, Eventos, o GA4 permite criar um evento a partir de outro, com condições de correspondência, ou modificar um existente, segundo a página de criar e modificar eventos. Exige papel de Editor. É possível mudar o valor de um parâmetro, copiar valor de outro parâmetro com a sintaxe [[nome_do_parametro]], renomear ou remover. Aritmética não é suportada.
- Limite de 50 eventos modificados e 50 criados.
- Não afeta dados históricos e pode levar uma hora ou mais.
- Não é possível criar ou modificar a partir de parâmetros da matriz items com gtag.js.
- Eventos enviados por Measurement Protocol, ou seja, de servidor, não podem ser modificados.
- Modificar page_view para uma página específica interrompe a coleta nas demais; crie um novo evento a partir dele.
- Renomear um evento-chave remove o status de evento-chave.
Registrar o parâmetro: o passo que faz o dado aparecer
Enviar o parâmetro não basta para analisá-lo. A página de dimensões e métricas personalizadas descreve o fluxo: adicionar o parâmetro no código, enviar dados reais, criar a dimensão ou a métrica em Administrador, Definições personalizadas, e aguardar de 24 a 48 horas para usar em relatórios e anúncios. A documentação não afirma literalmente que o parâmetro não aparece sem registro; trate isso como leitura do fluxo descrito. Parâmetros não registrados ficam visíveis, por exemplo, no DebugView.
| Escopo | O que registra | Exemplo |
|---|---|---|
| Evento | Parâmetro de evento, para dado categórico | click_location, payment_method |
| Usuário | Propriedade do usuário | tipo_de_cliente |
| Item | Atributo dentro da matriz items | cor, tamanho |
| Métrica personalizada | Valor numérico de um parâmetro de evento | discount_value, shipping_cost |
| Métrica calculada | Combinação de métricas | Receita por sessão (exemplo) |
Cardinalidade e privacidade
Evite registrar valores únicos por usuário, identificadores de sessão e carimbos de hora, porque os valores podem cair na linha (Outros). A documentação também alerta para não registrar algo que já é predefinido, como página ou ID da transação. Em privacidade, a política sobre dados que não podem ser enviados proíbe informações que possam ser reconhecidas como pessoais, como e-mail, telefone pessoal, CPF, CNPJ e nomes, e pede atenção a parâmetros de evento, termos de busca interna e UTMs. Uma busca interna com termo livre exige sanitização.
Plano de medição para um e-commerce brasileiro
A tabela abaixo é uma proposta da Analytikos para eventos que o Google não recomenda de forma nativa. Use recomendados, como search, add_shipping_info e purchase, onde existirem.
| Evento | Quando dispara | Parâmetros | Registrar como |
|---|---|---|---|
| click_whatsapp | Clique no botão de WhatsApp | click_location (header, pdp, rodape, flutuante), page_type | Dimensões de evento: click_location, page_type |
| filter_apply | Aplicação de filtro na listagem | filter_type, filter_value, results_count | Dimensões: filter_type, filter_value; métrica: results_count |
| coupon_apply | Cupom aplicado no carrinho | coupon_type, coupon_status, discount_value | Dimensões: coupon_type, coupon_status; métrica: discount_value |
| shipping_select | Escolha do frete | shipping_method, shipping_cost, shipping_days | Dimensão: shipping_method; métricas: shipping_cost, shipping_days |
| payment_method_select | Escolha de Pix, boleto ou cartão | payment_method, installments | Dimensão: payment_method; métrica: installments |
Um cuidado com o coupon_code: se a lista de cupons for grande, a cardinalidade sobe. Prefira coupon_type, com valores como percentual, frete_gratis e valor_fixo. No caso do clique no botão, o passo a passo do gatilho está em como rastrear cliques no WhatsApp como conversão no GA4.
Exemplo numérico hipotético
Uma loja com 20.000 sessões no mês registra 600 eventos payment_method_select. A distribuição é 360 Pix (60%), 150 cartão (25%) e 90 boleto (15%). Com a dimensão payment_method e a métrica installments registradas, a soma de parcelas nos 150 pedidos de cartão pode ser 480, o que dá 480 ÷ 150 = 3,2 parcelas em média. Se 200 eventos coupon_apply somam R$ 3.000 em discount_value, o desconto médio é 3.000 ÷ 200 = R$ 15 por cupom. O plano inteiro usa 6 eventos, cerca de 9 dimensões de evento e 4 métricas, bem abaixo das cotas de 50.
Validação no DebugView
A página do DebugView orienta ativar o modo de depuração pelo Tag Assistant, pelo modo de visualização do GTM ou pelo parâmetro debug_mode: true no config ou no evento. Para desativar, remova o parâmetro: definir como false não funciona. O DebugView mostra os eventos dos últimos 60 segundos com parâmetros e os dos últimos 30 minutos agregados, e não aparece se o Consent Mode ou controles de privacidade impedem o uso de cookies. Tráfego em modo debug pode distorcer relatórios, então filtre tráfego de desenvolvedor. A rotina completa de revisão está no checklist de auditoria de GA4.
- Disparar o evento no site com o Preview do GTM aberto.
- Conferir no DebugView o nome do evento e todos os parâmetros esperados.
- Registrar as dimensões e métricas em Definições personalizadas.
- Aguardar de 24 a 48 horas e abrir uma exploração com a dimensão.
- Marcar como evento-chave só o que representa resultado de negócio.
Erros comuns
Os erros abaixo concentram a maior parte dos problemas de eventos personalizados. Em cada um, a tabela mostra por que acontece, qual o efeito e como corrigir.
Erros de nomenclatura e de desenho
| Erro | Por que acontece e qual o efeito | Como corrigir |
|---|---|---|
| Nome fora da regra (espaço, hífen, começa com número) | Copia-se o texto do botão. O evento é rejeitado ou fragmentado | Usar snake_case e começar por letra |
| Mistura de maiúsculas e minúsculas | Várias pessoas implementam. Click_Whatsapp e click_whatsapp viram dois eventos e os dados se dividem | Padronizar em minúsculas e documentar |
| Nome ou prefixo reservado | Reaproveita-se um nome óbvio, como form_submit ou parâmetros com ga_. Há erro na interface ou conflito | Conferir a lista de reservados antes de criar |
| Criar personalizado onde há recomendado | Falta de consulta à documentação. Perde-se compatibilidade com relatórios e recursos futuros | Usar o evento recomendado e seus parâmetros |
| Mais de 25 parâmetros em um evento | Reaproveita-se o mesmo objeto em todos os eventos. Parâmetros excedentes são perdidos | Enviar só o que será analisado |
Erros de registro e de cota
| Erro | Por que acontece e qual o efeito | Como corrigir |
|---|---|---|
| Não registrar o parâmetro | Acha-se que enviar basta. O dado não aparece em relatórios e explorações | Criar a dimensão ou a métrica em Definições personalizadas |
| Esperar o dado na hora | Pressa em validar. O parâmetro leva de 24 a 48 horas para ficar disponível | Validar no DebugView e voltar no dia seguinte |
| Estourar a cota | Registra-se todo parâmetro por garantia. Ao atingir o limite, só é possível adicionar outro 48 horas depois de excluir uma dimensão | Registrar só o que será usado e remover duplicatas |
| Parâmetro de alta cardinalidade | Quer-se detalhe máximo, como ID de pedido ou carimbo de hora. Os valores caem em (Outros) | Agrupar valores em categorias |
| Valor acima de 100 caracteres | Envia-se URL ou texto longo. O valor é truncado ou ignorado | Enviar versão curta e padronizada |
Erros de operação e de privacidade
| Erro | Por que acontece e qual o efeito | Como corrigir |
|---|---|---|
| Dado pessoal em parâmetro, URL ou busca | Captura-se o valor do formulário sem sanitizar. Há violação da política do Google e risco com a LGPD | Remover e-mail, CPF, nome e telefone antes do envio |
| Pular o DebugView | Corte de etapa de QA. Eventos saem duplicados, sem parâmetro ou fora de ordem | Validar antes de publicar o contêiner |
| Sobrescrever o dataLayer | Código escrito por times diferentes. As tags deixam de disparar de forma consistente | Usar window.dataLayer = window.dataLayer || [] |
| Alterar evento-chave ou modificar page_view | Mexe-se sem ler as ressalvas. O evento perde o status de chave ou a coleta para nas demais páginas | Criar um novo evento em vez de modificar |
| Tráfego de teste na produção | Debug ligado em ambiente real. Os relatórios ficam distorcidos | Filtrar tráfego de desenvolvedor |
Checklist de eventos personalizados
- O evento já existe como recomendado? Se sim, use o nome do Google.
- Nome em snake_case, até 40 caracteres, começando por letra e fora da lista de reservados.
- Plano de medição documentado com nome, gatilho, parâmetros e responsável.
- No máximo 25 parâmetros por evento, valores abaixo de 100 caracteres.
- Nenhum dado pessoal em parâmetros, URLs ou termos de busca.
- Evento validado no DebugView e no Preview do GTM.
- Dimensões e métricas registradas e cota monitorada.
- Eventos-chave marcados apenas para resultados de negócio.
Perguntas frequentes
Qual a diferença entre evento recomendado e personalizado?
O recomendado tem nome e parâmetros definidos pelo Google, o que garante compatibilidade com relatórios atuais e futuros. O personalizado tem nome definido por você e só deve ser criado quando nenhum outro tipo atende ao caso.
Qual é o limite de nomes de evento distintos no GA4?
Segundo a página de limites, não há limite de nomes distintos para fluxos web. Para fluxos de app o limite é de 500 por usuário de app. Confira a página oficial, porque limites podem mudar.
Por que meu parâmetro não aparece nos relatórios?
Em geral, porque não foi registrado como dimensão ou métrica personalizada. Depois do registro, a documentação indica de 24 a 48 horas para o uso em relatórios. Antes disso, o parâmetro pode ser visto no DebugView.
Quantos parâmetros posso enviar por evento?
Até 25 parâmetros por evento. O nome do parâmetro aceita até 40 caracteres e o valor, até 100, com exceções para page_title, page_referrer e page_location.
Posso enviar e-mail ou CPF como parâmetro?
Não. A política do Google Analytics proíbe dados que possam ser reconhecidos como pessoais, incluindo e-mail, telefone pessoal, CPF e CNPJ. Remova esses dados de parâmetros, URLs e termos de busca interna.
Preciso do GTM para criar eventos personalizados?
Não. É possível enviar com gtag.js direto no código ou criar eventos na interface do GA4 a partir de outros eventos. O GTM é uma forma comum de disparar a tag sem alterar o código a cada mudança.
Criar evento na interface altera dados antigos?
Não. Segundo a documentação, a criação e a modificação de eventos não afetam dados históricos e podem levar uma hora ou mais para começar a valer.
