Como validar evento enviado pelo Measurement Protocol GA4

O endpoint de validação do Measurement Protocol testa formato e regras do payload sem inserir o evento nos relatórios. Isso é diferente do endpoint de coleta de produção. Um HTTP bem-sucedido não prova que evento malformado foi aceito; examine validationMessages.

Exemplo para validar com valores fictícios

Para um fluxo web, a requisição usa Measurement ID e API secret na query; o corpo inclui client_id e eventos. Guarde API secret em variável de ambiente no servidor: não coloque segredo em JavaScript público, URL compartilhada, repositório ou log.

curl -sS -X POST \
  'https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=SEGREDO_DE_TESTE' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "555.123",
    "validation_behavior": "ENFORCE_RECOMMENDATIONS",
    "events": [{
      "name": "generate_lead",
      "params": {
        "currency": "BRL",
        "value": 100.00,
        "lead_type": "site_institucional"
      }
    }]
  }'

Substitua Measurement ID e segredo por valores de teste sob seu controle; não inclua email, nome, telefone ou identificador que revele pessoa nesse exemplo. A documentação informa que endpoint de validação é /debug/mp/collect, em oposição ao /mp/collect de produção.

Interprete e corrija o resultado

Uma resposta sem mensagens deve conter:

{"validationMessages": []}

Se houver problema, leia fieldPath, description e validationCode: por exemplo, nome de evento inválido, parâmetro obrigatório ausente ou valor fora dos limites. Corrija o campo apontado e reenvie. Com ENFORCE_RECOMMENDATIONS, o verificador também aplica regras recomendadas mais estritas. Não ignore aviso só porque não bloqueou a requisição.

Depois da sintaxe, valide a implantação

1. Confirme que measurement_id pertence ao fluxo certo e que api_secret está correto e ativo; o endpoint de depuração não valida esses dois valores.
2. Verifique no ambiente de teste que o servidor realmente envia ao /mp/collect com credenciais protegidas e dados de cliente válidos/conformes à política aplicável.
3. Use DebugView/Realtime para verificar evento efetivamente recebido no fluxo; a resposta de validação não aparece nos relatórios.
4. Compare evento, consentimento, momento de disparo e deduplicação com a ação real. client_id deve corresponder ao cliente web quando esse modelo se aplicar; não invente um novo por evento.
5. Nunca exponha API secret no navegador. Remova logs de query que possam reter segredo e faça rotação se ele for publicado acidentalmente.

Consulte validar eventos — Google Analytics, que documenta corpo, rota de depuração e resposta. Veja também eventos do GA4.