Validar eventos

Escolha sua plataforma:

O Measurement Protocol do Google Analytics não retorna códigos de erro HTTP, mesmo que um evento esteja incorreto ou não tenha os parâmetros necessários. Para verificar se os eventos são válidos, teste-os no servidor de validação do Measurement Protocol antes de implantá-los na produção. Depois de validar se os eventos estão estruturados corretamente, verifique a implementação para ter certeza de que você está usando as chaves corretas.

Chame o servidor de validação diretamente ou use o Criador de eventos do Google Analytics. O Criador de eventos do Google Analytics permite criar eventos de forma interativa e usa o servidor de validação do Measurement Protocol para validá-los.

Neste guia, descrevemos como enviar eventos para o servidor de validação do Measurement Protocol para Google Analytics 4 e interpretar a resposta.

Enviar eventos para validação

A única diferença na solicitação de eventos enviados para o Measurement Protocol e o servidor de validação do Measurement Protocol é o URL.

Servidor	URL
Measurement Protocol	`/mp/collect`
Servidor de validação do Measurement Protocol	`/debug/mp/collect`

Todos os outros campos de solicitação são os mesmos.

Recomendamos a seguinte abordagem para validação:

Use verificações de validação estritas durante o desenvolvimento com uma das seguintes opções:
- Valide solicitações com o Criador de eventos.
- Envie solicitações ao servidor de validação com validation_behavior definido como ENFORCE_RECOMMENDATIONS.
Em produção, envie solicitações sem validation_behavior definido para minimizar os dados rejeitados pelo Measurement Protocol.

Exemplo de um evento inválido

O código a seguir mostra um evento inválido que está sendo enviado ao servidor de validação do Measurement Protocol:

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/debug/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    validation_behavior: "ENFORCE_RECOMMENDATIONS",
    events: [{
      // Event names must start with an alphabetic character.
      name: "_badEventName",
      params: {},
    }]
  })
});

Exemplo de um evento válido

O código a seguir mostra um evento válido que está sendo enviado ao servidor de validação do Measurement Protocol. Essa solicitação resultaria em uma matriz validationMessages vazia na resposta, como mostrado na seção Resposta de validação.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/debug/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    validation_behavior: "ENFORCE_RECOMMENDATIONS",
    events: [{
      name: "level_up",
      params: {
        level: 2,
        character: "MyHero"
      },
    }]
  })
});

Resposta de validação

Confira a resposta do servidor de validação ao exemplo de evento inválido.

{
  "validationMessages": [
    {
      "fieldPath": "events",
      "description": "Event at index: [0] has invalid name [_badEventName]. Names must start with an alphabetic character.",
      "validationCode": "NAME_INVALID"
    }
  ]
}

Esta é a resposta do servidor de validação a uma solicitação sem problemas de validação:

{
  "validationMessages": []
}

Resposta

Chave	Tipo	Descrição
`validationMessages`	Array<ValidationMessage>	Matriz de mensagens de validação.

ValidationMessage

Chave	Tipo	Descrição
`fieldPath`	string	Caminho para o campo inválido.
`description`	string	Descrição do erro.
`validationCode`	ValidationCode	Um código de validação que corresponde ao erro.

ValidationCode

Valor	Descrição
`VALUE_INVALID`	O valor informado para `fieldPath` é inválido. Veja as limitações.
`VALUE_REQUIRED`	Um valor obrigatório não foi informado para um `fieldPath`.
`NAME_INVALID`	O nome informado é inválido. Veja as limitações.
`NAME_RESERVED`	O nome informado é um dos nomes reservados. Veja os nomes reservados.
`VALUE_OUT_OF_BOUNDS`	O valor informado é muito grande. Veja as limitações.
`EXCEEDED_MAX_ENTITIES`	Havia muitos parâmetros na solicitação. Veja as limitações.
`NAME_DUPLICATED`	O mesmo nome foi informado mais de uma vez na solicitação.