Como os parâmetros de evento do GA4 carregam os detalhes de cada evento

O que são os parâmetros de evento do GA4?

Todo evento que o Google Analytics 4 registra carrega parâmetros de evento do GA4, os pares chave-valor que dizem qual link foi clicado, quanto valeu uma compra ou qual produto um visitante viu. O nome do evento diz o que aconteceu. Os parâmetros dizem os detalhes. O guia para desenvolvedores do Google resume em uma linha: "Parameters provide additional information about the ways users interact with your website."

A central de ajuda do Google faz a mesma divisão entre as três camadas de dados do GA4: "Events measure what users do on your website or app, like clicking a link or watching a video. Event parameters provide more details about these actions, like which link was clicked or how much of the video a user watched. User properties tell you more about the users themselves." Se o modelo de eventos em si é novo para você, comece pelo tracking de eventos e volte aqui para a camada dos parâmetros.

Quais parâmetros o GA4 coleta sem nenhum código?

O GA4 anexa um conjunto de parâmetros a todos os eventos de um fluxo da web, incluindo os eventos personalizados, antes que você escreva uma linha de código de tracking. A lista do Google de parâmetros "collected by default with every event, including custom events" traz language, page_location, page_referrer, page_title e screen_resolution para fluxos da web. O GA4 também gera ga_session_id e ga_session_number a cada sessão e envia engagement_time_msec com eventos como user_engagement e page_view.

Os eventos recomendados acrescentam uma segunda camada: parâmetros que o Google já nomeou e ligou aos relatórios predefinidos. O evento purchase é o que a maioria dos times usa:

A referência do Google acrescenta uma regra que quebra os relatórios de receita quando é ignorada: "If you set value then currency is required for revenue metrics to be computed accurately." Os parâmetros de eventos coletados automaticamente e de eventos recomendados preenchem dimensões e métricas predefinidas. Tudo o que você inventa por conta própria não preenche.

Como enviar um parâmetro de evento personalizado?

Você envia um parâmetro de evento personalizado adicionando-o como par chave-valor no terceiro argumento da chamada gtag('event', ...). O guia do Google mostra a estrutura como gtag('event', '<event_name>', {<event_parameters>}); com este exemplo:

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Aqui, app_name e screen_name são os nomes dos parâmetros, e myAppName e Home são os valores. Para anexar um parâmetro a todos os eventos de uma página, coloque-o no comando config, como em gtag('config', 'G-XXXXXXXXXX', {'page_title': 'Contact Us', 'currency': 'EUR'}). O Google desaconselha a terceira opção para valores personalizados: "The set command may not reliably propagate custom parameters to all Google Analytics measurement streams." Use event ou config para tudo o que você criou.

Confira o resultado no relatório Realtime ou no DebugView. Nas palavras do Google, "These reports show data as it arrives." O DebugView lista o conjunto combinado, incluindo os valores aplicados globalmente, na aba Parameters do evento.

Por que um parâmetro personalizado não aparece nos relatórios do GA4?

Um parâmetro personalizado não aparece nos relatórios do GA4 porque o Google só faz relatórios sobre ele depois que você o registra como dimensão ou métrica personalizada. O guia para desenvolvedores diz isso sem rodeios: "Without this registration, the parameter data is collected but isn't available for reporting." O Realtime e o DebugView mostram o valor bruto, e é por isso que um parâmetro pode parecer certo nos testes e ainda assim faltar em todas as explorações uma semana depois.

O registro leva dois minutos na tela de administração. A página de ajuda do Google lista os passos:

1. Em Admin, na seção Data display, clique em Custom definitions.
2. Abra a aba Custom dimensions e clique em Create custom dimensions.
3. Digite um Dimension name. O Google aceita underscores e espaços aqui, mas não hífens.
4. Defina Scope como Event.
5. Em Event parameter, digite o nome do parâmetro exatamente como o seu código o envia.
6. Clique em Save.

Dois campos não têm volta. O Google marca tanto Scope quanto Event parameter com "You can't change this field after you save the new dimension." Um erro de digitação no nome do parâmetro obriga a apagar a dimensão e criá-la de novo. Depois de salvar, o Google diz que você pode adicionar a dimensão aos relatórios "after 24-48 hours from when the custom data was sent and the custom dimension was created." Durante essa janela, a dimensão aparece como uma das causas documentadas de (not set) no GA4. As páginas do Google não dizem nada sobre preencher valores coletados antes de a dimensão existir, então registre a dimensão no mesmo dia em que o parâmetro for ao ar.

Números seguem outro caminho. Um parâmetro que mede uma quantidade, como segundos assistidos ou itens no carrinho, vai em uma métrica personalizada. A regra do Google é que, para "categorical data, however, such as what text was clicked or which page was viewed, it's more appropriate to use an event-scoped custom dimension."

Quais limites valem para os parâmetros de evento do GA4?

Os parâmetros de evento do GA4 têm limite de 25 por evento, 40 caracteres por nome e 100 caracteres por valor, e o Google não registra nada acima desses limites. A página de limites de coleta diz: "Google Analytics doesn't log events, event parameters, and user properties that exceed the following limits."

O Google diz que migrar para o Analytics 360 permite "increase certain limits (but not event/parameter character limits)", então os tamanhos de nome e de valor são os mesmos em qualquer propriedade. O limite que pesa na maioria dos sites são as 50 dimensões personalizadas com escopo de evento, não os 25 parâmetros por evento, porque cada dimensão cobre um nome de parâmetro em todos os eventos que o enviam. Chegar ao teto de dimensões também tem um custo: o Google diz que "you'll need to wait 48 hours after deleting dimensions to add new ones."

Quais nomes de parâmetro o GA4 reserva?

O GA4 reserva cinco prefixos e uma lista de nomes para parâmetros de evento, e um nome reservado não pode alimentar uma dimensão personalizada. As regras de nomenclatura do Google dizem que os nomes de parâmetro "can't begin with" underscore, firebase_, ga_, google_ ou gtag.. Os nomes reservados para dimensões e métricas personalizadas são cid, currency, customer_id, customerid, dclid, gclid, session_id, sessionid, sfmc_id, sid, srsltid, uid, user_id e userid.

Maiúsculas e minúsculas importam nos eventos, e o mesmo hábito é seguro para os parâmetros. As regras do Google afirmam "Event names are case sensitive. For example, my_event and My_Event are distinct events." Escolha um estilo, como snake case em minúsculas, e mantenha-o em eventos e parâmetros, para que Plan e plan nunca acabem como duas colunas.

O que nunca deve ser enviado como parâmetro de evento?

Dados pessoais e identificadores únicos nunca devem ser enviados como parâmetros de evento do GA4. A política do Google diz que "no data be passed to Google that Google could use or recognize as personally identifiable information (PII)", com endereços de e-mail, números de celular pessoais e números de seguro social como exemplos. O vazamento mais comum é um valor de formulário ou uma query string da URL copiados para um parâmetro, e a seção sobre eventos e parâmetros em como o Google Analytics coleta dados de usuários mostra como isso acontece.

Valores únicos causam um segundo problema mesmo quando não são pessoais. O Google orienta as propriedades padrão a não criar "unnecessary high-cardinality custom dimensions" e dá três exemplos: um ID único por usuário, um ID único por sessão e um timestamp. Essas dimensões "may negatively impact your reports and explorations, and cause data to be condensed under the (other) row." Envie categorias, como plan: pro ou method: google, e não valores que mudam a cada hit.

Uma regra de parsing pega times de surpresa. O Google avisa que "any value in a custom dimension that resembles a number will be treated as a number, even if it was originally formatted as text", então um valor de texto "94E40" é lido como notação científica. Coloque um prefixo em códigos que parecem numéricos, como sku_94E40, para mantê-los como texto.

Como o Flowsery lida com dados de eventos personalizados?

O Flowsery registra um evento personalizado com uma única chamada, como window.flowsery("signup"), sem tag manager e sem etapa de registro de dimensão personalizada entre o código e o dashboard. O tracking de metas e eventos dele cobre cliques em botões, envios de formulário, downloads de arquivos e reproduções de vídeo, permite anexar valores de receita aos eventos e mostra cada um em um feed de eventos em tempo real no momento em que dispara, então você confere o tracking assim que o coloca no ar. Os eventos são rastreados sem cookies e sem dados pessoais. Se você está tirando um plano de eventos do GA4, a comparação em tracking de eventos personalizados em analytics com privacidade vs GA4 mostra quais hábitos do GA4 deixar para trás no caminho.

Perguntas frequentes

Quantos parâmetros de evento um evento do GA4 pode ter?

Um evento do GA4 pode carregar 25 parâmetros de evento em uma propriedade padrão. O Google não registra parâmetros além desse limite, então os valores extras nunca chegam aos relatórios. O Analytics 360 aumenta alguns limites, mas não os tetos de 40 caracteres por nome e 100 caracteres por valor.

Por que vejo meu parâmetro no DebugView, mas não nos relatórios?

O DebugView e o Realtime mostram os parâmetros brutos conforme chegam, enquanto os relatórios padrão e as explorações só mostram os parâmetros personalizados que você registrou como dimensões ou métricas personalizadas. Registre o parâmetro em Admin, Custom definitions, e espere de 24 a 48 horas para os dados aparecerem.

Qual é a diferença entre um parâmetro de evento e uma dimensão personalizada?

Um parâmetro de evento é o par chave-valor que o seu código envia com um evento. Uma dimensão personalizada é o campo de relatório que você cria no GA4 e que lê um nome de parâmetro em todos os eventos que o enviam. Uma dimensão personalizada com escopo de evento cobre um parâmetro em quantos eventos você quiser.

As dimensões personalizadas se aplicam a dados coletados antes de serem criadas?

As páginas de ajuda do Google não dizem que as dimensões personalizadas preenchem dados anteriores. Elas afirmam que você pode usar uma dimensão 24 a 48 horas depois de os dados serem enviados e de a dimensão ser criada. Registre a dimensão no dia em que o parâmetro for ao ar para evitar uma lacuna.

Posso enviar um ID de usuário como parâmetro de evento?

Não registre um ID de usuário como dimensão personalizada com escopo de evento. user_id está na lista de nomes reservados do Google, e o Google cita um ID único por usuário como uma dimensão de alta cardinalidade a evitar. Para esse caso, o Google indica o recurso User-ID.

O que acontece com um valor de parâmetro com mais de 100 caracteres?

O GA4 não registra um valor de parâmetro que ultrapasse o limite daquele parâmetro. O limite é de 100 caracteres para a maioria dos parâmetros, com as exceções de 300 para page_title, 420 para page_referrer e 1,000 para page_location. Corte os valores longos ou converta-os em categorias curtas antes de enviá-los.

Posso usar o comando set do gtag para enviar um parâmetro personalizado?

O Google desaconselha isso. O comando set pode não propagar de forma confiável os parâmetros personalizados para todos os streams de mensuração do Google Analytics. Envie valores personalizados com event ou config, os dois comandos que o Google recomenda para isso.

Quantos parâmetros personalizados um item de ecommerce pode carregar?

A tabela de limites fixa os parâmetros personalizados no nível do item em 27 por evento de ecommerce, além dos parâmetros de item que o GA4 já exige, como item_id e item_name. Esse limite é separado do teto de 25 parâmetros por evento.

O nome de uma dimensão personalizada pode ter hífen?

A regra do Google na tela de administração permite underscores e espaços no nome de uma dimensão personalizada, mas não hífens. Use letras, números, underscores e espaços para evitar um erro de validação ao salvar.

O que acontece se eu excluir uma dimensão personalizada por engano?

A espera vale quando você já atingiu o limite de dimensões personalizadas. A nota do Google diz: "If you hit the limit for custom dimensions, you'll need to wait 48 hours after deleting dimensions to add new ones." Com as 50 vagas de escopo de evento ocupadas, excluir a dimensão errada para abrir espaço custa dois dias até você poder recriá-la.