A marcação GA4 do lado do cliente via gtag.js ou GTM é a linha de base de atribuição à qual a maioria das equipas recorre por predefinição. Funciona bem em condições ideais: um utilizador Chrome no desktop com uma ligação rápida, sem bloqueador de anúncios, uma sessão Safari que não acionou o limite de 24 horas de cookies definidos por script do ITP. As condições ideais cobrem talvez 65-75% do tráfego da UE em 2026.
O restante - utilizadores do uBlock Origin, bloqueio integrado do Brave, Intelligent Tracking Prevention do Safari no iOS, o crescente grupo de bloqueadores ao nível da rede como NextDNS e Pi-hole - envia eventos que ou são descartados antes de chegarem a www.google-analytics.com ou chegam sem um identificador de cliente utilizável porque o cookie _ga foi apagado. A lacuna típica em audiências com forte presença da UE é de 25-35% dos eventos de conversão. Para alguns setores - fintech, ferramentas de privacidade, ferramentas de programação - é maior porque o perfil demográfico dos utilizadores está correlacionado com a adoção de bloqueadores de anúncios.
O Measurement Protocol do GA4 é o caminho do lado do servidor que contorna tudo isso. O seu servidor comunica diretamente com o endpoint de recolha do Google. O estado do browser é irrelevante. Esta publicação cobre a configuração exata: credenciais, forma do payload, junção do client_id, validação e o padrão de deduplicação para equipas que executam o gtag ao lado do caminho do lado do servidor.
A arquitetura subjacente de encaminhamento de conversões - por que o lado do servidor ganha e como funciona o fan-out para várias plataformas - está coberta na visão geral de rastreamento de conversões do lado do servidor. A versão Meta CAPI deste tutorial está em encaminhamento de conversões para Meta CAPI; o padrão de configuração tem a mesma forma, com parâmetros específicos do GA4 aqui.
TL;DR#
- O gtag.js do GA4 perde 25-35% dos eventos de conversão em tráfego típico da UE para bloqueadores de anúncios (uBlock, Brave) e ITP (limites de duração de cookies do Safari); o Measurement Protocol contorna tudo isso porque o pedido tem origem no seu servidor.
- Precisa de duas credenciais: o Measurement ID (
G-XXXXXXXX) da sua stream de dados, e um segredo de API gerado em Admin → Streams de dados → Segredos de API do Measurement Protocol. Ambos são colados nas definições do espaço de trabalho do Elido em menos de dois minutos. - O
client_idé o que liga um evento do lado do servidor a uma sessão GA4; o Elido define um cookie UUID de origem própria no redirecionamento de ligação curta e inclui-o em cada encaminhamento de conversão, por isso não precisa de ler o cookie_gado browser. - A validação demora cerca de dez minutos: o DebugView do GA4 mostra os eventos do Measurement Protocol a chegar em aproximadamente dez segundos; os relatórios padrão são atualizados em 24-48 horas.
As duas credenciais de que precisa#
O Measurement Protocol do GA4 requer duas informações, ambas da consola de Admin do GA4.
Measurement ID. O identificador da stream de dados, formatado como G-XXXXXXXX. Encontre-o em Admin → Streams de dados → a sua stream web → o painel de detalhes da stream. Este é o mesmo ID que passa para gtag('config', 'G-XXXXXXXX') na sua configuração do lado do cliente - não é um segredo; aparece no código fonte da sua página.
Segredo de API. Esta é a credencial que autoriza escritas do lado do servidor para o endpoint de recolha. Navegue para Admin → Streams de dados → a sua stream web → Segredos de API do Measurement Protocol → Criar. O segredo é uma cadeia alfanumérica curta. Trate-o como uma chave de conta de serviço: armazene-o como um segredo de espaço de trabalho, rode-o com outras credenciais de serviço, não o confirme no código fonte.
No Elido, estes são colados nas Definições do Espaço de Trabalho em Integrações → GA4. Uma vez guardados, o Elido valida o par contra o endpoint de depuração do GA4 e confirma a conectividade. A validação é imediata; um 4xx neste passo significa que o Measurement ID ou o segredo de API está errado.
A forma do evento#
A referência do Measurement Protocol do GA4 (acedida a 12-05-2026) especifica o formato do pedido. O endpoint é:
POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=<secret>
O corpo transporta um client_id, um user_id opcional e um array events. Aqui está o payload para um evento de compra:
{
"client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"user_id": "user-shop-12847",
"events": [
{
"name": "purchase",
"params": {
"transaction_id": "ord_98231",
"value": 89.5,
"currency": "EUR",
"engagement_time_msec": 1,
"items": [
{
"item_id": "sku-spring-jeans-32-blue",
"item_name": "Spring Jeans 32 Blue",
"quantity": 1,
"price": 89.5
}
]
}
}
]
}
Algumas coisas neste payload que são fáceis de errar:
event_name deve ser snake_case em minúsculas. A referência de eventos do GA4 (acedida a 12-05-2026) lista os nomes de eventos recomendados: purchase, sign_up, generate_lead, add_to_cart. Enviar Purchase (P maiúsculo) irá produzir um evento separado nos relatórios do GA4 em vez de se fundir com os seus eventos purchase disparados pelo gtag. A plataforma não o avisa; o evento simplesmente aparece como um evento personalizado com um nome estranho.
engagement_time_msec deve estar presente e definido como um inteiro positivo. Sem ele, o GA4 conta o evento, mas não credita o engagement da sessão, e alguns modelos de atribuição excluem eventos sem tempo de engagement. Definir 1 é suficiente para satisfazer o requisito.
event_params está limitado a 25 parâmetros por evento. O Measurement Protocol irá rejeitar payloads que excedam este limite. A rejeição é silenciosa por predefinição - o pedido devolve 204 sem corpo independentemente de o evento ter sido aceite. Use o endpoint de depuração (coberto na secção de validação) para apanhar excedentes.
user_id é opcional, mas valioso. Se tiver um identificador de utilizador persistente no lado do servidor - um ID de cliente na sua tabela de encomendas, um ID de subscritor no seu CRM - envie-o. O GA4 usa-o para atribuição entre dispositivos, e melhora a correspondência entre eventos do lado do servidor e do lado do cliente.
Junção do client_id: por que é importante e como o Elido a gere#
O client_id é o campo que o GA4 usa para ligar um evento do lado do servidor a uma sessão de browser. Quando o gtag.js é executado numa página, lê o cookie _ga e usa o seu UUID como client_id para todos os eventos que dispara. Se o seu evento do lado do servidor transportar o mesmo client_id, o GA4 pode juntar esses eventos na mesma jornada e sessão do utilizador.
O desafio é colocar esse UUID no lado do servidor. O cookie _ga é um cookie de origem própria no seu domínio, por isso o seu servidor pode lê-lo no momento do checkout e incluí-lo no payload de conversão. Mas isso só funciona se o browser do utilizador tiver _ga definido, que é exatamente a população que perde para ITP e bloqueadores de anúncios.
O Elido resolve isso na camada de redirecionamento. Quando um utilizador clica numa ligação curta, o handler edge do Elido gera um UUID e define-o como um cookie _elido_cid de origem própria na resposta de redirecionamento - antes de o utilizador chegar ao seu site. O UUID também é adicionado ao URL de destino como ?elido_click=<uuid> (configurável por espaço de trabalho). O fluxo:
A sua página de destino ou gestor de tags lê elido_click do URL e escreve-o nos atributos personalizados da encomenda. No momento da conversão, o seu webhook de encomenda transporta o UUID. O Elido procura-o, constrói o payload do Measurement Protocol com client_id definido para esse UUID, e encaminha para o GA4.
Isto é mais fiável do que ler _ga do browser porque o UUID é capturado no momento do clique, antes de a sessão do browser do utilizador determinar se os cookies são aceites. Mesmo que o ITP apague o cookie _ga dentro de 24 horas, o cookie _elido_cid do Elido persiste como um cookie de origem própria sob o seu domínio de ligação curta - e o atributo de encomenda persiste na sua base de dados independentemente.
O guia de envio de eventos do GA4 (acedido a 12-05-2026) descreve como o client_id funciona entre caminhos de cliente e servidor.
Encaminhamentos do Elido: o curl real#
Quando POST /v1/conversions chega com um click_id, o Elido monta o payload do Measurement Protocol e encaminha-o. Para chamar o endpoint diretamente - contornando o Elido e testando o lado GA4 MP da ligação - o curl é:
curl -X POST \
"https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"user_id": "user-shop-12847",
"events": [
{
"name": "purchase",
"params": {
"transaction_id": "ord_98231",
"value": 89.50,
"currency": "EUR",
"engagement_time_msec": 1
}
}
]
}'
O GA4 devolve 204 tanto para eventos válidos como inválidos. Não é possível distinguir um evento mal formado de uma ingestão bem-sucedida apenas pelo código de estado HTTP. Para ver se o evento realmente chegou, use o endpoint de depuração durante o desenvolvimento:
POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET
O endpoint de depuração devolve um corpo JSON que lista os erros de validação para cada evento. Um evento com um nome de parâmetro errado, um payload que excede 25 parâmetros, ou um client_id mal formado irá aparecer aqui.
Ao usar o Elido, a mesma visibilidade de validação está disponível via GET /v1/conversions/{id} - o registo de conversão mostra o estado do encaminhamento GA4 e qualquer resposta de erro do endpoint de depuração durante o modo de teste.
Validação: DebugView#
O DebugView do GA4 é o ciclo de feedback mais rápido durante a configuração. Para ativá-lo para eventos do lado do servidor, adicione "debug_mode": 1 ao objeto params do evento. Os eventos com este indicador aparecem no DebugView em aproximadamente dez segundos; não contam para os dados do relatório de produção.
No DebugView (GA4 Admin → DebugView), cada evento mostra o seu nome, os parâmetros que transportou, e se algum parâmetro foi rejeitado. A vista agrupa os eventos por client_id, para que possa rastrear a sessão completa do clique até à conversão.
O que verificar antes de remover debug_mode:
- O nome do evento aparece exatamente como esperado no fluxo de eventos do DebugView (
purchase, nãoPurchaseouecommerce_purchase). - O parâmetro
transaction_idestá visível e corresponde ao formato do seu ID de encomenda. - O
client_idé uma cadeia no formato UUID - não vazio, não uma cadeia de fallback"unknown". - O
currencyé o código ISO 4217 correto (EUR, nãoeur, nãoEuro).
Os relatórios GA4 padrão demoram 24-48 horas para refletir os dados de conversão do lado do servidor. Não avalie a precisão dos relatórios no primeiro dia. O DebugView confirma a forma do evento; os relatórios confirmam a atribuição e os totais.
Erros comuns#
client_id em falta. Os eventos sem client_id são descartados silenciosamente pelo Measurement Protocol. Este é o modo de falha individual mais comum. A perda é invisível - o pedido devolve 204, o DebugView não mostra nada, a conversão nunca aparece. Verifique se o campo client_id está sempre preenchido antes de o pedido ser enviado. Na configuração do Elido, um client_id em falta significa que o parâmetro elido_click não foi escrito na encomenda no momento da conversão - verifique a tag da página de destino ou o handler do webhook.
Formato errado do nome do evento. Purchase cria um evento personalizado chamado Purchase ao lado dos eventos purchase existentes do gtag. A sua contagem total de compras nos relatórios GA4 divide-se em dois nomes de eventos. A correção é impor snake_case em minúsculas em todos os nomes de eventos enviados para o endpoint do Measurement Protocol. A referência de eventos do GA4 (linkada acima) lista os nomes canónicos para eventos de ecommerce.
Exceder 25 event_params. O Measurement Protocol rejeita silenciosamente payloads com mais de 25 parâmetros por evento. Equipas a encaminhar metadados de encomendas completos (todos os itens de linha, todos os atributos personalizados) frequentemente atingem este limite sem se aperceberem. Use o endpoint de depuração para apanhar excedentes no desenvolvimento. Em produção, elimine parâmetros não essenciais e mantenha os payloads de eventos enxutos.
Moeda obtida da configuração da página, não da encomenda. Se a sua configuração do gtag usa USD como predefinição, mas as suas encomendas são em EUR, o evento do lado do servidor e o evento do lado do cliente transportam valores de moeda diferentes. O GA4 regista-os com o mesmo nome de evento, mas não consegue agregar os valores. Obtenha a moeda do registo de encomenda no seu backend, não de uma configuração gtag ao nível da página.
Deduplicação com gtag do lado do cliente#
Se executar o gtag.js do lado do cliente e o Measurement Protocol do lado do servidor em simultâneo, precisa de deduplicação. O GA4 deduplica os eventos usando client_id combinado com uma janela de timestamp. O mecanismo é menos explícito do que o campo event_id do Meta CAPI, mas a abordagem prática é a mesma: transportar um transaction_id consistente em eventos de compra em ambos os caminhos.
Para eventos de compra, defina transaction_id para o seu ID de encomenda. O seu gtag do lado do browser dispara purchase com transaction_id: "ord_98231" quando a página de confirmação carrega; o seu evento do Measurement Protocol do lado do servidor transporta o mesmo transaction_id: "ord_98231". O GA4 deduplica dentro da mesma janela de sessão. Se a mesma combinação client_id + transaction_id chegar duas vezes dentro da janela de dedup, a segunda é ignorada.
Para eventos a montante - generate_lead, sign_up, add_to_cart - não há ID de encomenda para usar. O ID de clique funciona aqui: defina event_id para o UUID elido_click. Tanto o pixel do lado do browser como o encaminhamento do lado do servidor referenciam o mesmo valor. Esta é a mesma disciplina descrita no tutorial de rastreamento UTM de ponta a ponta, que cobre a configuração de marcação de campanha mais ampla que torna este ID disponível ao longo do funil.
A janela de dedup no GA4 não está documentada publicamente com a precisão que a Meta publica para o CAPI. Na prática, os eventos com client_id + transaction_id correspondentes a chegar dentro da mesma janela de sessão são deduplicados. Executar ambos os caminhos em simultâneo é a configuração mais segura - fornece cobertura de fallback para a audiência com muitos bloqueadores de anúncios enquanto dá ao algoritmo um sinal mais limpo do caminho do servidor.
Onde isto se encaixa no pipeline de atribuição#
O Measurement Protocol fecha a lacuna de sinal do GA4 da mesma forma que o CAPI fecha a lacuna de sinal da Meta. Os mecanismos são diferentes - o GA4 usa client_id e transaction_id onde a Meta usa event_id e chaves de correspondência - mas a arquitetura é idêntica: um evento do lado do servidor que não depende do estado do browser.
Para a visão completa de quais plataformas encaminhar e como o fan-out funciona à escala, a visão geral de rastreamento de conversões do lado do servidor cobre GA4, Meta CAPI e TikTok Events lado a lado. Para campanhas onde a marcação UTM é o passo a montante, rastreamento de campanhas UTM de ponta a ponta é a leitura prévia.
A superfície do produto para esta configuração: funcionalidades de rastreamento de conversões documenta a API /v1/conversions completa, incluindo fan-out multi-plataforma, eventos de reembolso e semântica de retry. Soluções para marketers mostra como o pipeline de conversão se encaixa num fluxo de trabalho de campanha ao lado de modelos UTM e roteamento de smart links.
A própria configuração - credenciais nas definições do espaço de trabalho, passo do gestor de tags para elido_click na página de destino, ligação do webhook de encomenda - demora meio dia para a maioria das equipas. O passo de validação do DebugView acrescenta mais trinta minutos. O resultado são dados de conversão GA4 que refletem o que as suas campanhas estão realmente a conduzir, não os 65-75% que sobrevivem ao caminho do lado do browser.
Fontes
- Google Analytics 4: Visão geral do Measurement Protocol. developers.google.com/analytics/devguides/collection/protocol/ga4 (acedido a 12-05-2026)
- GA4 Measurement Protocol: Referência de eventos. developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events (acedido a 12-05-2026)
- GA4 Measurement Protocol: Envio de eventos. developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events (acedido a 12-05-2026)
Experimente Elido
Cole uma URL, obtenha um link curto
Sem cadastro. O link vive 30 dias. Cadastre-se para mantê-lo para sempre.
Grátis, sem necessidade de registo · 2 por dia