O que são as dimensões do
GA4, quais usar, seus nomes na API, os limites por propriedade e como criar uma dimensão personalizada passo a passo.

Nesta página
Em resumo
Uma dimensão do Google Analytics é um atributo de texto que descreve seus dados, como o país de um visitante, o dispositivo que ele usou ou a página onde a sessão começou. As dimensões dão contexto a métricas como sessões ou conversões. Comece pelas dimensões integradas e crie uma dimensão personalizada só quando essa lista não responder à sua pergunta, dentro dos limites da sua propriedade (50 de escopo evento e 25 de escopo usuário em uma propriedade padrão).
Quer ir mais longe? Pergunte ao
Quiz rápido
Qual forma de medir seu marketing combina com você?
O Sorank combina com suas respostas
Teste por 3 dias no seu próprio site e veja onde você está no Google, no ChatGPT e nas outras IAs.
Teste grátis de 3 dias3 dias grátis, depois você para quando quiser. Garantia de resultados de 90 dias, sujeita a condições.
Cada número em um relatório do GA4 tem um rótulo. O número é uma métrica. O rótulo é uma dimensão. «412 sessões» é uma métrica. «412 sessões da Alemanha no celular» acrescenta duas dimensões, o país e a categoria do dispositivo, que indicam quais visitantes geraram esse número.
A referência da Central de Ajuda do Google Analytics faz a mesma distinção. Dimensões são atributos descritivos, em texto ou categorias. Métricas são quantidades. Médias, taxas e porcentagens contam como métricas, mesmo quando são calculadas a partir de outras métricas. Você pode somar sessões entre linhas. Não pode somar países. Você os agrupa.
Por isso a mesma métrica pode significar coisas diferentes. Uma taxa de engajamento de 60% em uma página de destino se lê de um jeito bem diferente quando você sabe que os visitantes vieram da sua newsletter e não de uma campanha paga. A dimensão diz quem chegou. A métrica diz quantos deles fizeram alguma coisa.
Se o GA4 é novo para você, leia antes nosso verbete do glossário sobre o GA4 e volte aqui depois. Este guia pressupõe que os dados já chegam a uma propriedade do GA4.
Dimensão ou métrica?
Guias antigos falam em «dimensão personalizada, índice 1» e em escopos no nível de hit. Esse mundo acabou. O Google parou de processar novos hits em propriedades padrão do Universal Analytics em 1º de julho de 2023. As propriedades 360 que tinham um contrato vigente ganharam tempo extra de processamento até 1º de julho de 2024. Se a sua equipe ainda fala em números de índice, abandone esse hábito. No GA4, você dá um nome a cada dimensão personalizada e a liga a um parâmetro que seu site ou aplicativo envia.
Datas de encerramento do Universal Analytics
Fonte: Central de Ajuda do Google Analytics, «O Google Analytics 4 substituiu o Universal Analytics»
A página da Central de Ajuda do Google sobre dimensões e métricas agrupa as dimensões integradas em 16 categorias: Atribuição, Dados demográficos, E-commerce, Evento, Jogos, Geral, Geografia, Link, Página / tela, Plataforma / dispositivo, Publisher, Tempo, Origem do tráfego, Usuário, Tempo de vida do usuário e Vídeo. A mesma página também lista 11 categorias de métricas, como Sessão, Receita e Publicidade. Mantenha as duas listas separadas ao pesquisar, porque uma categoria de métricas não vai ajudar a filtrar por país.

Você não precisa decorar a lista. Precisa saber qual categoria tem a resposta para a sua pergunta. Quatro categorias cobrem a maior parte do trabalho em um site de conteúdo:
Depois vêm as dimensões de Evento e de Usuário. As dimensões de Evento descrevem uma ação, como um clique em um botão ou a reprodução de um vídeo. As dimensões de Usuário descrevem o visitante ao longo das sessões, como a origem que o trouxe pela primeira vez ao seu site. Saber essa divisão mostra se uma pergunta pertence a uma sessão, a um evento ou a um usuário. Misturar esses níveis é um dos motivos mais comuns para um relatório parecer errado, e voltamos a isso na seção sobre erros.

Cada dimensão tem dois nomes. O nome da interface é o que você vê em um relatório. O nome da API é o que você envia para a API de Dados do Google Analytics, e ele é necessário para exportações, scripts e painéis. O Google documenta os nomes da API no seu esquema da API de Dados. A tabela abaixo reúne as dimensões que a maioria dos sites de conteúdo usa.
| Nome na interface | Nome da API | Pergunta que responde |
|---|---|---|
| Origem da sessão | sessionSource | Qual site ou plataforma iniciou a sessão |
| Mídia da sessão | sessionMedium | Que tipo de tráfego foi, como organic, referral ou cpc |
| Grupo de canais padrão da sessão | sessionDefaultChannelGroup | A qual grupo de canais a sessão pertence |
| Página de destino | landingPage | A primeira página da sessão |
| Caminho da página | pagePath | A parte do caminho de cada página que o visitante abriu |
| País | country | De onde veio a atividade do usuário |
| Categoria do dispositivo | deviceCategory | Computador, tablet ou celular |
| Nome do evento | eventName | Qual evento foi registrado |
| Data | date | A data do evento, no formato AAAAMMDD |

Três regras ajudam quando você passa da interface para a API. Primeiro, os nomes da API diferenciam maiúsculas de minúsculas: sessionSource não é SessionSource. Segundo, cada dimensão extra divide cada linha em mais linhas, o que deixa o resultado mais difícil de ler, então comece com duas ou três. Terceiro, uma solicitação que cita uma dimensão desconhecida pela sua propriedade falha. Esse último ponto importa mais para as dimensões personalizadas.
Dimensões personalizadas seguem outro padrão. O esquema do Google as referencia por escopo e nome do parâmetro. Uma dimensão de escopo evento é escrita como customEvent: seguido do nome do parâmetro. Uma dimensão de escopo usuário é escrita como customUser: seguido do nome do seu parâmetro. O exemplo abaixo pede a origem da sessão e uma dimensão personalizada de escopo evento chamada author_name, dos últimos 28 dias. Troque os nomes pelos seus.
{
"dimensions": [
{ "name": "sessionSource" },
{ "name": "customEvent:author_name" }
],
"metrics": [{ "name": "sessions" }],
"dateRanges": [{ "startDate": "28daysAgo", "endDate": "yesterday" }]
}
Essa solicitação só funciona se a sua propriedade tiver registrado author_name como dimensão personalizada de escopo evento. Caso contrário, ela falha. Registre primeiro e depois consulte.
Nota
Dimensões registradas antes de outubro de 2020 usam uma forma mais longa que inclui o nome do evento entre colchetes, como customEvent:parameter_name[event_name]. Se uma consulta que funcionava no ano passado falha agora, verifique se a dimensão é uma dessas antigas.
Uma dimensão principal é aquela pela qual o relatório é agrupado. Cada linha é um valor dessa dimensão. Uma dimensão secundária acrescenta um segundo detalhamento dentro de cada linha. A ideia é simples, mas é aqui que a maioria das pessoas trava, porque os mesmos dados respondem a uma pergunta diferente dependendo de qual dimensão vem primeiro.
| Pergunta | Dimensão principal | Dimensão secundária | O que você descobre |
|---|---|---|---|
| Quais páginas recebem visitas orgânicas? | Página de destino | Origem / mídia da sessão | Se a busca é a fonte principal de cada página, ou se a página depende de outros canais |
| Os visitantes de um mercado usam mais o celular? | País | Categoria do dispositivo | A participação do celular em cada país, que indica onde testar os layouts primeiro |
| Quais campanhas levam a quais páginas? | Campanha da sessão | Página de destino | Campanhas enviadas para páginas que não combinam com a oferta |
| Quais navegadores os visitantes de um país usam? | Navegador | País | Problemas de compatibilidade que só aparecem em um mercado |
Em uma tabela de Explorações você pode empilhar mais de duas dimensões, mas a legibilidade cai rápido. Fique com duas ou três por visualização e passe o restante para filtros. Um filtro remove linhas, e uma dimensão as divide. Use filtros para restringir a pergunta e dimensões para explicar a resposta.
Pegue a primeira linha da tabela acima. Se a página de destino for a dimensão principal e a origem da sessão a secundária, cada linha é uma página com o tráfego dividido por origem. Inverta, e cada linha passa a ser uma origem com as páginas listadas embaixo. Os números são idênticos. A pergunta é outra. Decida qual você precisa antes de abrir o relatório, e anote em uma frase.
As dimensões padrão cobrem a maioria dos relatórios. Você precisa de uma dimensão personalizada quando a informação está no seu próprio sistema, ou em um parâmetro que você envia. Os casos típicos são o nome do autor em um blog, o tipo de plano em um aplicativo SaaS, uma categoria de conteúdo ou se o visitante estava logado. Antes de criar qualquer coisa, faça uma pergunta: a lista integrada consegue responder? Se sim, pare por aí.
O escopo define o que a dimensão personalizada descreve. Uma dimensão de escopo evento está ligada a um único evento, como um clique ou uma visualização de página que carrega um parâmetro. Uma dimensão de escopo usuário está ligada a um visitante e mantém o mesmo valor em todas as suas sessões, como um nível de plano. Uma dimensão de escopo item está ligada a um único item dentro de um evento de e-commerce, como a cor de um produto.
| Escopo | Está ligado a | Uso típico | Propriedade padrão | Propriedade 360 |
|---|---|---|---|---|
| Evento | Um evento | Autor do artigo lido | 50 | 125 |
| Usuário | Um visitante | Nível do plano, status de login | 25 | 100 |
| Item | Um item de um evento de e-commerce | Marca ou cor do produto | 10 | 25 |
Limites de dimensões personalizadas em uma propriedade padrão
Fonte: Central de Ajuda do Google Analytics, visão geral de dimensões e métricas personalizadas
Os limites se aplicam por propriedade e contam cada dimensão registrada. A página Definições personalizadas em Administrador mostra o seu uso. Abra o link Informações sobre a cota, no canto superior direito, para ver quantos espaços ainda restam. Mantenha essa página aberta sempre que planejar uma mudança de medição.
Se você atingir o limite, liberar um espaço não é imediato. A página da Central de Ajuda do Google sobre os limites de dimensões personalizadas diz que você precisa esperar 48 horas depois de excluir dimensões antes de poder adicionar novas. Planeje seus nomes antes de começar, e não crie uma dimensão para um teste pontual que vai excluir na semana seguinte.

Atenção
Nunca envie dados pessoais como valor de dimensão. Nomes, endereços de e-mail e números de telefone são informações pessoais identificáveis, e as regras do Google proíbem enviá-los ao Analytics. O nome de um autor não tem problema. O e-mail de um cliente tem, mesmo que esteja criptografado no seu código.
Estes passos pressupõem que o seu site ou aplicativo já envia o parâmetro. Se nenhum dado chegar, a dimensão é criada, mas não mostra nada. Siga a lista na ordem.
Criar uma dimensão personalizada em cinco passos
Fonte: Central de Ajuda do Google Analytics, «[GA4] Sobre dimensões e métricas personalizadas»
Abra o DebugView e dispare o evento no seu site ou aplicativo. Olhe o evento e os parâmetros. Confirme se o valor é o esperado, por exemplo «Jane Doe» para um autor e não «undefined». Só então crie a dimensão. Um parâmetro que envia o valor errado vai encher seus relatórios de dados incorretos a partir daquele dia, e os dias anteriores não podem ser corrigidos.
O nome do parâmetro na interface precisa ser igual ao nome que o seu código envia. Uma letra de diferença, uma maiúscula ou um espaço criam uma dimensão que nunca se preenche. Copie o nome do código em vez de digitá-lo de memória. Use letras minúsculas e sublinhados, como em author_name, porque você vai colar a mesma string em solicitações de API depois.
Nota
A página da Central de Ajuda do Google sobre dimensões personalizadas do GA4 diz que os relatórios começam de 24 a 48 horas depois de criar uma dimensão. Não crie uma dimensão na tarde do lançamento de uma campanha esperando dados no mesmo dia. Crie-a alguns dias antes e depois confira.
Quando as dimensões existem, você pode lê-las em quatro lugares. Cada um serve a um trabalho diferente. Escolher a ferramenta errada custa tempo, então compare antes de montar qualquer coisa.
| Método | Ideal para | Limite principal | Exemplo |
|---|---|---|---|
| Relatórios padrão | Verificações rápidas de tráfego, páginas e eventos | Layouts fixos com uma dimensão principal e uma secundária | Aquisição de tráfego por origem da sessão |
| Explorações | Tabelas personalizadas, funis e análise de caminhos | Exige configuração, e tabelas grandes ficam lentas | Página de destino por origem da sessão e categoria do dispositivo |
| API de Dados | Exportações, scripts e seus próprios painéis | Exige código, e cada dimensão precisa estar registrada | Exportação semanal de sessões por página para uma planilha |
| Looker Studio | Relatórios compartilhados com clientes ou gestores | Depende do conector e da frequência de atualização dele | Painel mensal para o cliente com o tráfego por canal |
Os relatórios padrão respondem à primeira pergunta que você tem toda manhã. Use-os para notar uma queda e depois passe para uma ferramenta mais flexível para achar a causa. A vantagem é a velocidade. A fraqueza é que você não pode escolher qualquer par de dimensões, então uma pergunta que precisa de três dimensões não cabe em um relatório padrão.
As Explorações permitem montar uma tabela com as dimensões e métricas que você escolher, e salvá-la para depois. É a ferramenta para analisar páginas de destino, comparar canais dentro de um mesmo país e verificar se uma dimensão personalizada realmente se preenche. Limite cada exploração a uma pergunta. Uma tabela que responde a cinco perguntas normalmente não responde a nenhuma com clareza.
Dica
Dimensões limpas começam com links de campanha limpos. Os valores de origem e mídia vêm dos seus parâmetros UTM, então uma diferença de escrita como «Newsletter» e «newsletter» cria uma segunda linha para o mesmo canal. Crie seus links com o nosso gerador de links UTM gratuito para manter os nomes consistentes.
Use a API quando um relatório roda toda semana, quando você alimenta um painel ou quando quer comparar a saída de duas propriedades em um script. O padrão de solicitação mostrado antes neste guia é a peça básica. Quando ele funcionar em um teste, coloque o mesmo JSON no seu script e mantenha os nomes das dimensões em um único lugar, para que uma renomeação não quebre dez consultas de uma vez.
O Looker Studio é a escolha comum quando outra pessoa precisa ler os números. Ele se conecta ao GA4 e apresenta as dimensões em gráficos e tabelas. Seus limites vêm do conector e da frequência de atualização, não do GA4 em si. Se você está montando um painel para cliente, nosso guia do Looker Studio para SEO cobre as fórmulas e os limites que importam para dados de busca, e nosso guia de um painel do GA4 explica o que colocar na primeira tela.
Assistentes de IA enviam visitantes que chegam por um link, e esse link carrega uma origem de referência. Você vê isso na dimensão origem da sessão e na página de destino. Alguns aplicativos de IA não repassam nenhum referenciador, então este método capta só parte do quadro. Nosso verbete do glossário sobre tráfego oculto de IA explica o que falta e por quê. Para a busca orgânica no mesmo relatório, nosso guia do Google Analytics para SEO mostra como separá-la do resto.
Isolar as visitas de IA em quatro passos
Leia o resultado com cuidado. Um aumento de sessões de IA em uma página mostra que a página é usada, mas não diz se os visitantes compraram algo. Adicione uma métrica de conversão à tabela antes de decidir que uma página funciona. O artigo sobre medir citações de IA com o Google Analytics percorre a parte das conversões.
Dica
Se você quer o tráfego do Google e o de IA em uma única tela sem montar a exploração sozinho, o painel GEO / SEO da Sorank mostra os dois. Ele combina dados do Google Search Console (cliques, impressões, CTR, posição) com as visualizações de página que os assistentes de IA enviam, conforme registradas no Google Analytics.
A maioria dos problemas com dimensões aparece como uma coluna vazia, uma coluna de valores «(not set)» ou um relatório que parece correto, mas responde à pergunta errada. A tabela mostra o sinal a procurar. As seções seguintes explicam cada erro.
| Erro | Como identificar | Correção |
|---|---|---|
| Criar uma dimensão antes de os dados chegarem | Todas as linhas mostram «(not set)» | Confirme o valor no DebugView e só então crie a dimensão |
| Nome diferente entre o código e a interface | Sem dados 48 horas depois | Copie o nome do parâmetro a partir do código |
| Duplicar uma dimensão integrada | Duas dimensões dão as mesmas linhas | Revise primeiro a lista padrão e depois exclua a cópia |
| Valores de alta cardinalidade | Milhares de linhas, cada uma com uma única sessão | Envie categorias e guarde os identificadores únicos no seu próprio sistema |
| Dados pessoais em um valor | Valores que parecem e-mails ou nomes completos | Remova o parâmetro e envie uma categoria no lugar |
| Esperar histórico | As datas antigas estão vazias, as novas estão preenchidas | Compare só a partir da data de criação e anote a lacuna |
O erro: você cria a dimensão e depois descobre que o parâmetro nunca chegou ao GA4. Dá para notar porque cada linha do relatório mostra «(not set)». A correção é inverter a ordem. Confirme o valor no DebugView, registre a dimensão e espere as 24 a 48 horas que o Google indica antes de julgar o relatório.
O erro: o código envia author_name, mas a interface tem Author_name ou author name. A dimensão existe e fica vazia. O sinal: uma definição personalizada normal sem dados depois de dois dias. A correção: abra o código, copie a string exata e confira de novo no DebugView. Corrigir depois não recupera os dias perdidos, então conserte no dia em que encontrar.
O erro: você cria uma dimensão personalizada chamada Country porque não conferiu a lista padrão. Você percebe por duas linhas com os mesmos valores. O custo é a cota. Cada duplicata usa uma das suas 50 vagas de escopo evento, ou uma das 25 de escopo usuário, e essas vagas você vai precisar depois para coisas que o GA4 não consegue oferecer. Revise primeiro a lista padrão nos relatórios e depois decida.
O erro: você envia uma dimensão com um valor único para cada visitante ou cada pedido, como um ID de usuário, uma URL completa com string de consulta ou um número de pedido. O Google recomenda evitar dimensões de alta cardinalidade em propriedades padrão. O sinal: uma tabela com milhares de linhas, cada uma com uma única sessão. A correção é enviar uma categoria. Envie o tipo de plano, não o ID do usuário. Envie o tipo de conteúdo, não a URL completa. Guarde o identificador único no seu CRM, onde você pode cruzá-lo com os dados por conta própria.
O erro: uma dimensão contém um e-mail, um nome ou um telefone, muitas vezes porque alguém usou uma variável conveniente. O sinal: um valor que parece uma pessoa. A correção é remover o parâmetro e enviar uma categoria ou um código interno anônimo. Consulte o seu encarregado de proteção de dados se tiver dúvida. Criptografar um e-mail não o torna seguro para envio.
O erro: você cria uma dimensão em maio e espera que ela explique as sessões de janeiro. Os relatórios só mostram valores coletados depois que a dimensão começou a recebê-los. O sinal: uma coluna vazia nas datas anteriores. A correção: informe a data de início no título do relatório e compare apenas a partir dela. Não apresente um gráfico de antes e depois que começa no meio de uma lacuna.
Uma dimensão é um atributo de texto, como país, dispositivo ou caminho da página. Uma métrica é um número, como sessões, usuários ativos ou conversões. As dimensões agrupam e rotulam os números, então a mesma métrica se lê de forma diferente conforme as dimensões com que você a combina.
Uma propriedade padrão permite 50 dimensões personalizadas de escopo evento, 25 de escopo usuário e 10 de escopo item. Uma propriedade 360 permite 125, 100 e 25. A página Definições personalizadas em Administrador mostra quantas você já usou. Excluir uma não libera a vaga na hora, porque é preciso esperar 48 horas antes de adicionar outra.
Normalmente o parâmetro não chega ao GA4, ou o nome não bate exatamente. Confira no DebugView, corrija o nome na interface ou no código e espere de 24 a 48 horas depois da criação. Se os dados continuarem sem aparecer, o parâmetro provavelmente não está sendo enviado.
Sua lista para esta semana
Comece com uma pergunta que você não consegue responder hoje. Monte uma dimensão para ela, confira os dados e só então adicione a próxima.
Uma dimensão é um atributo de texto, como país, dispositivo ou caminho da página. Uma métrica é um número, como sessões, usuários ativos ou conversões. As dimensões agrupam e rotulam os números.
Uma propriedade padrão permite 50 dimensões de escopo evento, 25 de escopo usuário e 10 de escopo item. Uma propriedade 360 permite 125, 100 e 25. A página Definições personalizadas em Administrador mostra o seu uso.
Normalmente o parâmetro não chega ao GA4, ou o nome não bate exatamente. Confira no DebugView, corrija o nome e espere de 24 a 48 horas depois da criação antes de julgar o relatório.
