Como uma convenção de nomes de eventos sobrevive à primeira renomeação

Por que uma convenção de nomes de eventos importa?

Escolher uma convenção de nomes de eventos é barato no dia um e caro no dia duzentos, porque o Google Analytics 4 nunca aplica uma renomeação aos dados que já coletou. Todo nome inconsistente que você coloca no ar vira uma segunda linha permanente em cada relatório que agrupa por evento, e a única forma de juntar essas linhas depois é recalcular os dados por conta própria em um data warehouse.

A falha não é teórica nem arrumadinha. Três desenvolvedores instrumentam o mesmo botão em três sprints e você fica com signup_click, SignupClick e click_signup. O GA4 trata os três como eventos separados, porque "event names are case sensitive. For example, my_event and My_Event are distinct events", ou seja, nomes de eventos diferenciam maiúsculas de minúsculas e essas duas grafias são eventos distintos. Seu funil se parte em três, sua contagem de eventos-chave fica em um terço da verdade, e ninguém percebe até alguém comparar o painel com o Stripe. A disciplina mais ampla está em rastreamento de eventos; esta página trata dos nomes em si.

Quais nomes o GA4 recusa de cara?

O GA4 rejeita nomes e prefixos reservados, e as regras de nomenclatura de eventos do Google dizem a consequência sem rodeios: "If you try to use a reserved prefix or name, Analytics will display an error message", isto é, ao usar um prefixo ou nome reservado você recebe uma mensagem de erro. As regras que valem para todo nome são curtas:

• "Event names must start with a letter. Use only letters, numbers, and underscores. Don't use spaces." Comece por uma letra, use apenas letras, números e underscores, e nada de espaços.
• "Event names are case sensitive." Maiúsculas e minúsculas contam.
• "Event names can include English and non-English words and letters." Palavras e letras fora do inglês são aceitas.

Para fluxos de dados da web, o Google reserva query_id como prefixo e reserva dezenove nomes de eventos diretamente. Os que atrapalham um time de implementação são justamente os que soam plausíveis, aqueles que você usaria por instinto:

Reservado na web	Por que você teria usado esse nome
click	O nome óbvio para qualquer handler de clique
error	O nome óbvio para uma falha no cliente
scroll	O nome óbvio para um evento de profundidade de rolagem
file_download	O nome óbvio para o download de um PDF
page_view	O nome óbvio para um pageview virtual em uma single-page app
session_start	O nome óbvio para o equivalente à abertura do app
user_engagement	O nome óbvio para um evento de tempo de permanência
video_start	O nome óbvio para um evento do player
ad_impression	O nome óbvio para um espaço de anúncio interno

A maioria deles já é enviada por você pela medição avançada, e é justamente por isso que estão reservados. Confira o que sua propriedade coleta sem configuração antes de nomear qualquer coisa, e veja autocapture para entender o que a coleta automática pega e o que não pega.

A referência do Measurement Protocol acrescenta uma segunda lista, mais longa, que vale quando você envia eventos pelo servidor, incluindo first_open, first_visit, app_exception, os_update e toda a família firebase_, e observa que "ad_impression, in_app_purchase and screen_view events are only allowed for App streams", ou seja, esses três eventos só valem para fluxos de app.

Os parâmetros têm as próprias reservas. O nome firebase_conversion é reservado, e nomes de parâmetros "cannot begin with" _, firebase_, ga_, google_ ou gtag., não podem começar com nenhum desses prefixos. Nomes de propriedades do usuário não podem começar com _, firebase_, ga_ ou google_, e os nomes first_open_time, first_visit_time, last_deep_link_referrer, user_id e first_open_after_install já estão ocupados.

Quais limites de tamanho se aplicam?

Quarenta caracteres para o nome do evento, e a punição por passar disso é mais estranha que uma recusa simples. Os limites de coleta de eventos do Google dizem que um nome de evento vai até "40 characters" e depois acrescentam: "If you mark an event as a key event and the event exceeds 40 characters, then the event will not be reported as a key event because the appended _c will be missing." Ou seja, se você marcar o evento como evento-chave e ele passar de 40 caracteres, ele deixa de ser reportado como evento-chave porque o _c anexado vai faltar. O evento continua sendo coletado. Ele só para de ser contável como evento-chave, em silêncio, porque o GA4 anexa _c internamente e o nome resultante estoura o limite.

Os limites ao redor moldam uma convenção tanto quanto o limite do nome:

Limite	Valor
Tamanho do nome do evento	40 caracteres
Nomes distintos de eventos, fluxo web	Sem limite
Nomes distintos de eventos, fluxo de app	500 por usuário do app
Parâmetros por evento	25
Tamanho do nome do parâmetro	40 caracteres
Tamanho do valor do parâmetro	100 caracteres
Valor de page_title	300 caracteres
Valor de page_referrer	420 caracteres
Valor de page_location	1.000 caracteres
Propriedades do usuário por propriedade	25
Tamanho do nome da propriedade do usuário	24 caracteres
Tamanho do valor da propriedade do usuário	36 caracteres

O valor de parâmetro de 100 caracteres é o que pega os times de surpresa. Um nome de produto, uma consulta de busca ou a string de erro de um formulário passam desse tamanho, e o valor é cortado em vez de o evento ser recusado. O nome de propriedade do usuário com 24 caracteres é ainda mais apertado, dezesseis caracteres abaixo do limite do nome do evento, o que é um bom motivo para não espelhar nomes de eventos em nomes de propriedades do usuário.

A contagem ilimitada de nomes distintos na web é uma armadilha, não uma licença. Nada impede você de publicar quatrocentos nomes de eventos; os relatórios é que ficam inutilizáveis, e cada nome precisa ser registrado como definição personalizada antes de aparecer na maioria das análises. Esse custo de registro está detalhado em como configurar dimensões personalizadas.

O objeto ou a ação vem primeiro?

O conselho corrente é objeto primeiro, cart_added e video_played, com o argumento de que os relatórios ordenam em ordem alfabética e nomes com objeto na frente agrupam todos os eventos do mesmo assunto. É um bom conselho e ele discorda do Google.

Os eventos recomendados do Google começam pela ação. Só o conjunto de varejo traz add_payment_info, add_shipping_info, add_to_cart, add_to_wishlist, begin_checkout, purchase, refund, remove_from_cart, select_item, view_item, e o conjunto geral acrescenta earn_virtual_currency, join_group, login, search, select_content, share, sign_up, spend_virtual_currency, tutorial_begin e tutorial_complete.

Isso importa porque eventos recomendados não são enfeite. O Google os descreve como "standardized events for different business verticals (e.g., retail, travel, games) that unlock prebuilt reporting panels", eventos padronizados por vertical de negócio que destravam painéis de relatório prontos, enquanto eventos personalizados são "events that you define yourself because no prepopulated automatic, enhanced, or recommended event fits your needs" e ficam "accessible using custom reports", ou seja, você mesmo os define quando nenhum evento pronto serve, e eles só aparecem em relatórios personalizados. Renomear add_to_cart para cart_added em nome da consistência interna custa os relatórios de ecommerce prontos.

A regra que funciona, portanto, separa por origem, não por gosto. Use a grafia do Google onde existir um evento recomendado, exatamente como publicada, e aplique seu próprio padrão de objeto primeiro apenas aos eventos que o Google não define. Uma convenção que produz add_to_cart ao lado de pricing_table_viewed parece inconsistente no papel e é a única versão que preserva ao mesmo tempo os relatórios e a ordenação. Qualquer que seja a ordem escolhida, snake_case em letras minúsculas é a única grafia que evita a armadilha das maiúsculas, já que uma convenção em que qualquer caractere pode variar de caixa é uma convenção que vai acabar sendo violada.

Escolher a ordem do nome do evento

1

Checar a lista de eventos recomendados. Ver se o Google já define um evento para o que você quer medir, como add_to_cart ou begin_checkout.

2

Correspondência encontrada. Usar a grafia exata do Google, com a ação primeiro, para manter os relatórios de ecommerce prontos.

3

Nenhuma correspondência. Aplicar seu próprio padrão objeto primeiro, a partir de uma lista fechada de verbos e objetos.

Quanto custa renomear um evento depois do lançamento?

Custa o histórico, para sempre, e custa uma das cinquenta vagas. A documentação do Google sobre renomeação de eventos não deixa dúvida sobre a primeira parte: "Modified and new events do not apply to historical data." Eventos modificados e novos não valem para dados históricos. A modificação reescreve os eventos só daqui para a frente. Toda linha que já está na propriedade mantém o nome antigo, e não existe reprocessamento para consertar isso.

Há outras duas restrições ao lado. "An hour or more passes before modifications take effect", uma hora ou mais se passa até a modificação entrar em vigor, então a correção não é imediata nem depois de feita. E "you can modify up to 50 existing events and create up to 50 events based on existing events", você pode modificar até 50 eventos existentes e criar até 50 eventos a partir deles, o que faz do recurso de modificação um kit de reparo, não uma camada de nomenclatura em que dá para se apoiar indefinidamente.

O custo prático de uma renomeação, então, é:

• Uma divisão permanente em todo relatório que agrupa por nome de evento, na data da mudança.
• Qualquer definição de evento-chave, público ou funil que use o nome antigo precisa ser duplicada no nome novo, ou para de contar. A diferença entre os dois conceitos está em eventos-chave versus conversões.
• Comparações ano a ano que cruzam essa fronteira precisam ser costuradas na mão.
• Uma das cinquenta vagas de modificação, ocupada enquanto o nome antigo continuar chegando de uma página em cache ou de uma versão do app que ainda não saiu.

Nada disso se recupera pagando mais ou esperando mais, que é todo o argumento para gastar uma tarde no documento de nomenclatura antes de a primeira tag ir para produção.

Como é uma convenção que funciona?

Uma convenção são quatro decisões escritas, não uma lista de nomes. Tome cada uma delas uma vez e a lista se gera sozinha.

Caixa: apenas snake_case em minúsculas, para nomes e parâmetros. Letras, números e underscores são tudo que o GA4 aceita de qualquer jeito, e as minúsculas eliminam a única forma de dois eventos idênticos divergirem.

Vocabulário: uma lista fechada de verbos e uma lista fechada de objetos. view, select, add, remove, submit, start, complete cobrem a maioria dos sites. Dois verbos com o mesmo significado é como signup_submit e signup_complete acabam os dois em produção.

Ordem: a grafia do Google onde existir um evento recomendado, objeto primeiro em todo o resto, e a exceção registrada no documento para que o próximo engenheiro não a normalize em silêncio.

Onde fica o detalhe: detalhe variável mora nos parâmetros, nunca no nome. form_submit com um parâmetro form_name é um evento que você consegue filtrar; newsletter_form_submit, contact_form_submit e demo_form_submit são três eventos que você não consegue comparar sem montar um relatório por formulário, e queimam três dos seus registros de definição personalizada em vez de um.

Tamanho: mantenha os nomes abaixo de 40 caracteres com folga, porque a penalidade do evento-chave anexa _c ao que você escolheu e a falha é silenciosa.

Perguntas frequentes

Quais caracteres um nome de evento do GA4 pode conter?

Letras, números e underscores, e o nome precisa começar por uma letra. O Google formula a regra assim: "Event names must start with a letter. Use only letters, numbers, and underscores. Don't use spaces." Letras fora do inglês são permitidas: "Event names can include English and non-English words and letters."

Nomes de eventos do GA4 diferenciam maiúsculas de minúsculas?

Sim. As regras de nomenclatura do Google dizem que "event names are case sensitive. For example, my_event and My_Event are distinct events." Não existe etapa de normalização, então duas grafias do mesmo evento produzem duas linhas independentes em todo relatório que agrupa por nome de evento.

O que acontece se eu enviar um nome de evento reservado?

O Analytics recusa e mostra um erro. As regras de nomenclatura dizem que "if you try to use a reserved prefix or name, Analytics will display an error message." Os nomes reservados na web incluem click, error, scroll, file_download, page_view, session_start, user_engagement e video_start.

Devo usar object_action ou action_object?

Use a grafia exata do Google para os eventos recomendados dele, que começam pela ação, e objeto primeiro para todo o resto. O conjunto recomendado do Google inclui add_to_cart, begin_checkout, select_item e view_item, e renomear esses eventos abre mão dos painéis de relatório prontos que o Google associa a eles.

Dá para renomear um evento do GA4 depois do lançamento?

Dá para renomear daqui para a frente e nunca para trás. O Google afirma que "modified and new events do not apply to historical data", que "an hour or more passes before modifications take effect" e que você "can modify up to 50 existing events and create up to 50 events based on existing events".

Qual é o tamanho máximo de um nome de evento no GA4?

40 caracteres. Passar disso tem uma consequência específica além da recusa: o Google avisa que "if you mark an event as a key event and the event exceeds 40 characters, then the event will not be reported as a key event because the appended _c will be missing."

O que acontece se um time usar nomes de eventos inconsistentes?

O GA4 trata cada variação como um evento diferente, porque os nomes de eventos diferenciam maiúsculas de minúsculas. Se três desenvolvedores nomeiam o mesmo botão como signup_click, SignupClick e click_signup, o resultado são três linhas separadas em cada relatório, o funil se divide em três e a contagem de eventos-chave cai para um terço do valor real. Quase ninguém percebe até comparar o painel com outra fonte de dados, como o Stripe.

Existe um limite de quantos nomes de evento posso enviar ao GA4?

Um stream de web não tem limite para a quantidade de nomes de evento distintos, mas essa ausência de limite joga contra você. Os nomes de evento aparecem sozinhos, mas cada parâmetro que você anexa precisa de um espaço de definição personalizada, então quatrocentos nomes rendem relatórios que ninguém consegue ler. Um stream de app, por outro lado, limita a 500 eventos distintos por usuário do app.

Qual é a diferença entre um evento personalizado e um evento recomendado?

Um evento recomendado é um dos nomes padronizados do Google para um setor como varejo ou viagens, e o Google diz que ele libera painéis de relatório prontos. Um evento personalizado você define por conta própria, porque nenhum evento automático, aprimorado ou recomendado se encaixa, e ele só aparece em relatórios personalizados que você constrói. Renomear add_to_cart para cart_added por consistência interna custa o painel pronto associado a ele.

Os eventos-chave continuam contando depois que renomeio o evento que eles rastreiam?

Não automaticamente. Qualquer definição de evento-chave, público ou funil que apontava para o nome antigo precisa ser duplicada para o nome novo, ou para de contar assim que a mudança entra em vigor. Essa duplicação não custa nenhum espaço de modificação; só o próprio renomeio consome um dos cinquenta que o GA4 permite.