Google Analytics 4
É a única fonte do caOS que não é plataforma de anúncio. Traz o que aconteceu no site (sessões, usuários, eventos, receita) e nunca o gasto de mídia. Gasto continua vindo do Meta, do Google Ads e das outras fontes; o GA4 é a outra metade.
Começar
Conectarlogin do Google, outro que o do Ads
Não se pede credencial a ninguém: é login do Google. O que precisa existir antes é acesso. Peça a quem administra o GA4 do cliente que dê acesso de leitura à conta Google que você vai usar.
O GA4 tem login próprio, separado do Google Ads. Conectar um não conecta o outro. São dois cartões, duas autorizações, e podem ser duas contas Google diferentes. Isso é comum: num mesmo cliente, quem administra o Ads raramente é quem administra o Analytics.
Escolher as properties é um passo à parte, e o GA4 não te leva até ele. Nos outros conectores o caOS abre essa tela sozinho depois de autorizar; no GA4 não. Volte a Fontes e escolha quais properties entram no workspace. Enquanto você não escolher, a property não aparece em lugar nenhum.
Sua credencial, e o que acontece com ela
Conectou uma vez, está conectado. A credencial se renova sozinha, indefinidamente. Você não precisa marcar data no calendário nem reconectar de tempos em tempos.
Só existe um jeito de a conexão cair: alguém revogar o acesso do lado da plataforma (senha trocada, pessoa removida da conta, autorização cancelada). Aí a conta aparece em Conexões perdidas e reconectar resolve, com as tags que ela já tinha.
A credencial fica cifrada de ponta a ponta. Ela é cifrada antes de ser gravada, e a chave não vive no banco: nem quem tem acesso ao banco lê o valor. Ninguém no caOS, nem você, vê a credencial de volta depois de salva; a tela mostra apenas que ela existe e está válida.
Só é lida a métrica que você pediu. O caOS não escreve na sua conta de anúncio para extrair dados, e não guarda dado pessoal de quem viu o anúncio. O tratamento segue a LGPD, e a exclusão é sua: revogar a conexão apaga a credencial guardada.
Referência
Métricas e dimensõeso que cada campo quer dizer
O GA4 não tem métrica de mídia paga: nada de custo, impressão ou clique. O que ele traz é comportamento no site, e o elo com a mídia é a campanha.
Métricas principais8
| Campo na API | O que é | Onde aparece |
|---|---|---|
| sessions | Visitas ao site. | É o número que o cliente costuma chamar de acesso. Não some entre dias, ver Bom saber. |
| engagedSessions | Sessões com engajamento, no critério do GA4. | Mais de 10 segundos, ou uma conversão, ou duas páginas. |
| engagementRate | Sessões engajadas ÷ sessões. | Recalcule a partir das somas se for agregar períodos. |
| activeUsers | Usuários ativos no período. | Não soma entre dias: a mesma pessoa contaria duas vezes. |
| newUsers | Usuários que chegaram pela primeira vez. | Bom para separar aquisição de retorno. |
| totalUsers | Todos os usuários do período. | Também não soma. |
| averageSessionDuration | Duração média da sessão, em segundos. | Média de médias não funciona: pondere pelas sessões. |
| sessionsPerUser | Sessões ÷ usuários. | Derivada, recalcule ao agregar. |
Dimensões3
| Campo na API | O que é | Onde aparece |
|---|---|---|
| sessionCampaignName | A campanha que trouxe a sessão. | É por aqui que o GA4 encontra a mídia. |
| sessionSource | De onde veio (google, facebook, direto). | Com sessionMedium, formam o par source/medium. |
| sessionDefaultChannelGroup | O canal, já agrupado pelo Google. | Use quando o cliente pensa em canal, não em campanha. |
Parâmetros do relatório
Os campos acima dizem o que volta. Estes parâmetros dizem como: eles decidem o grão da linha, o período que ela cobre e o que conta como conversão. Dois relatórios da mesma conta com números diferentes quase sempre diferem aqui.
| Parâmetro | O que muda | Valores |
|---|---|---|
| dimensions | O recorte de cada linha. | No máximo 9 por relatório. Acima disso a Data API devolve HTTP 400, e o caOS falha antes, com a mensagem certa. |
| metrics | As colunas de número. | No máximo 10 por relatório, e pelo menos 1. É o motivo de existirem seis relatórios em vez de um só. |
| dateRanges | O período. | Vem da fonte. Ontem sempre chega parcial, ver Atualização do dado. |
| dimensionFilter | Filtro sobre as dimensões. | Opcional. Filtrar reduz linhas, não muda a definição da métrica. |
| linha zerada | O que a API omite. | Linha com tudo zero não volta. O mesmo dia devolve mais linhas quando você pede mais métricas. |
Tudo que dá para puxar
As tabelas acima são as que a maior parte dos relatórios usa, mas você não está preso a elas. O catálogo inteiro do GA4 tem 6 tabelas e 81 campos, e ao montar a fonte você escolhe o que entra. O que aparece marcado como puxada por padrão é o que a fonte de exemplo usa; o resto está disponível do mesmo jeito.
A lista abaixo sai do próprio catálogo do Xtractor, o mesmo que a tela de nova fonte lê. Se um campo está aqui, a tela oferece.
ga4_acquisition_campaign puxada por padrão17 campos
date, sessionSource, sessionMedium, sessionSourceMedium, sessionCampaignId, sessionCampaignName, sessionDefaultChannelGroup, sessions, engagedSessions, activeUsers, newUsers, totalUsers, screenPageViews, bounceRate, engagementRate, averageSessionDuration, sessionsPerUser
ga4_ecommerce_campaign15 campos
date, sessionSource, sessionMedium, sessionCampaignId, sessionCampaignName, addToCarts, checkouts, ecommercePurchases, transactions, purchaseRevenue, totalRevenue, totalPurchasers, firstTimePurchasers, itemsViewed, itemsPurchased
ga4_channel_campaign14 campos
date, sessionDefaultChannelGroup, sessionSourceMedium, sessionCampaignId, sessionCampaignName, sessions, engagedSessions, activeUsers, newUsers, totalUsers, screenPageViews, totalRevenue, purchaseRevenue, transactions
analytics_campaign_performance13 campos
date, sessionManualCampaignName, sessionManualSourceMedium, sessionManualAdContent, addToCarts, checkouts, newUsers, purchaseRevenue, sessions, totalPurchasers, totalRevenue, transactions, engagedSessions
ga4_funnel_events12 campos
date, sessionDefaultChannelGroup, sessionSource, sessionMedium, eventName, eventCount, eventCountPerUser, eventValue, sessions, activeUsers, totalUsers, userEngagementDuration
ga4_item_performance10 campos
date, itemName, itemCategory, sessionCampaignName, itemRevenue, itemsPurchased, itemsViewed, itemsAddedToCart, itemsCheckedOut, itemDiscountAmount
As dimensões vêm sempre. Marcar uma única métrica traz junto todas as dimensões daquele relatório, por isso o número de campos salvos é maior do que o que você clicou.
São seis relatórios, e cada um é fechado. Não dá para misturar campos de dois: se você precisa de sessão e de receita juntas, use o relatório que traz as duas, ou extraia dois relatórios.
Saída
Onde os dados chegamplanilha e banco são coisas diferentes
Planilha do Google
Para quem monta relatório na mão
Escolha um relatório e marque as métricas. Como as dimensões vêm junto, a aba nasce com mais colunas do que você clicou.
Para cruzar com mídia, o campo de ligação é o nome da campanha. Só funciona se a marcação da campanha for a mesma dos dois lados.
BigQuery
Para quem vai modelar em cima
6 relatórios, todos por dia, e nenhum campo de mídia paga.
Campanha legado (UTM manual), aquisição por campanha, e-commerce por campanha, e canal com sessões e receita no mesmo recorte. O de canal existe justamente para entregar sessão e receita juntas: cruzar os outros dois não é um para um.
Confiança
Atualização do dadoontem é sempre parcial
A atribuição do GA4 leva cerca de dois dias para assentar. Medido: o dia de ontem chega com quase metade das sessões sem origem atribuída; de anteontem para trás, fica em torno de 2%. Relatório diário que fala do dia anterior publica um número em que metade do tráfego ainda não tem origem. Trate ontem como parcial.
Por isso o caOS relê os dias recentes a cada sincronização e reescreve o que mudou: a sessão de ontem que hoje ganhou origem aparece atribuída na sua planilha, sem você fazer nada.
Sessão não soma. É número estimado por consulta: reagregar o diário não devolve exatamente o mensal. Receita e transações, ao contrário, batem exato.
Linha com tudo zerado não vem. Isso confunde conferência: o mesmo dia devolve mais linhas quando você pede mais métricas. Ao comparar com a interface do GA4, peça as mesmas métricas dos dois lados.
Detalhe
Bom sabero que costuma gerar dúvida
O relatório de campanha legado só enxerga UTM digitado à mão. O que vem por marcação automática do Google Ads não entra nele. Medido numa property real: a campanha manual cobre pouco menos da metade das sessões. Para campanha de Google Ads, use os relatórios de aquisição ou de canal.
O GA4 ocupa uma vaga de plataforma no seu plano. Se o limite já estiver cheio, a fonte é recusada na hora de salvar.
Tenha em mãos qual property é a do cliente. O caOS lista todas que o login alcança, e um login de agência costuma alcançar dezenas.
Suporte
Quando dá erradoa mensagem e o que fazer
Cartão com cadeado e “sem conexão”. Não existe conexão GA4 ainda. Conecte primeiro, monte a fonte depois.
“State token expired or already used.” A janela ficou aberta mais de dez minutos, ou o link foi usado duas vezes.
Autenticou e nenhuma property aparece. A leitura das properties falhou. Ou o login não tem acesso a property nenhuma, ou foi usada a conta Google errada.
As properties apareceram, mas não estão em Fontes. Falta escolhê-las: no GA4 esse passo não abre sozinho.
Um login com muitas contas do Analytics traz só parte delas. A busca pede uma página e não pede a seguinte, e o excedente é ignorado sem aviso.