Enviar eventos do Measurement Protocol para o Google Analytics

Este guia explica como enviar a um servidor do Google Analytics os eventos de fluxos de app e Web do Measurement Protocol do Google Analytics. Assim você pode conferir eventos do Measurement Protocol nos seus relatórios do Google Analytics.

Escolha a plataforma a ser retratada neste guia:

Formatar a solicitação

O Measurement Protocol do Google Analytics só oferece suporte a solicitações POST HTTP.

Para enviar um evento, use este formato:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

É necessário informar o seguinte no URL da solicitação:

  • api_secret: a chave secreta da API gerada na interface do Google Analytics.

    Para criar um novo secret, navegue até Administrador > Coleta e modificação de dados > Fluxos de dados > escolha seu fluxo > Secrets da API do Measurement Protocol > Criar.

  • firebase_app_id: o ID do app Firebase, que fica no console do Firebase em Configurações do projeto > Geral > Seus apps > ID do app.

    O firebase_app_id não é igual ao app_instance_id. O firebase_app_id identifica seu app, e o app_instance_id identifica uma única instalação do app.

É necessário fornecer um corpo de solicitação no formato JSON POST para o Measurement Protocol. Veja um exemplo:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Embora session_start seja um nome de evento reservado, criar um novo session_id gera uma nova sessão sem a necessidade de enviar session_start. Saiba como as sessões são contabilizadas.

Testar

Confira um exemplo que você pode usar para enviar vários eventos de uma só vez. Este exemplo envia um tutorial_begin evento e um join_group evento para o servidor do Google Analytics, inclui informações geográficas usando o campo user_location e inclui informações do dispositivo usando o campo device.

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

fetch(`https://www.google-analytics.com/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",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

O formato de firebase_app_id é específico da plataforma. Consulte o ID do aplicativo em Objetos e arquivos de configuração do Firebase.

Substituir o carimbo de data/hora

O Measurement Protocol usa o primeiro carimbo de data/hora encontrado na lista a seguir para cada evento e propriedade do usuário na solicitação:

  1. O timestamp_micros do evento ou da propriedade do usuário.
  2. O timestamp_micros da solicitação.
  3. O horário em que o Measurement Protocol recebe a solicitação.

O exemplo a seguir envia um carimbo de data/hora no nível da solicitação que se aplica a todos os eventos e propriedades do usuário na solicitação. Como resultado, o Measurement Protocol atribui um carimbo de data/hora de requestUnixEpochTimeInMicros aos eventos tutorial_begin e join_group e à propriedade do usuário customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

O exemplo a seguir envia um carimbo de data/hora no nível da solicitação, um carimbo de data/hora no nível do evento e um carimbo de data/hora no nível da propriedade do usuário. Como resultado, o Measurement Protocol atribui os seguintes carimbos de data/hora:

  • tutorialBeginUnixEpochTimeInMicros para o evento tutorial_begin
  • customerTierUnixEpochTimeInMicros para a propriedade do usuário customer_tier
  • requestUnixEpochTimeInMicros para o evento join_group e a propriedade do usuário newsletter_reader.
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Comportamento de validação para eventos e propriedades do usuário anteriores

Os eventos e as propriedades do usuário podem ser atualizados em até 72 horas. Se o valor timestamp_micros for anterior a 72 horas, o Measurement Protocol aceitará ou rejeitará o evento ou a propriedade do usuário da seguinte maneira:

  • Se o validation_behavior não estiver definido ou estiver definido como RELAXED, o Measurement Protocol aceitará o evento ou a propriedade do usuário, mas substituirá o carimbo de data/hora por 72 horas atrás.
  • Se o validation_behavior estiver definido como ENFORCE_RECOMMENDATIONS, o Measurement Protocol rejeitará o evento ou a propriedade do usuário.

Os eventos enviados usando o Measurement Protocol que devem ser unidos ou processados em conjunto com eventos coletados pelo SDK do Google Analytics para Firebase ou gtag.js precisam ser recebidos pelo Google Analytics em até 48 horas do carimbo de data/hora original do evento do lado do cliente. Os eventos recebidos depois desse período podem não ser processados conforme o esperado, principalmente para fins como atribuição de conversão.

Limitações

As limitações a seguir são válidas para o envio de eventos do Measurement Protocol ao Google Analytics:

  • As solicitações podem ter no máximo 25 eventos.
  • Os eventos podem ter no máximo 25 parâmetros.
  • Os eventos podem ter até 25 propriedades do usuário.
  • Os nomes das propriedades do usuário podem ter, no máximo, 24 caracteres.
  • Os valores de propriedade do usuário precisam ter, no máximo, 36 caracteres.
  • Os nomes dos eventos precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.
  • Os nomes dos parâmetros (incluindo os parâmetros de item) precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.

  • Os valores dos parâmetros (incluindo os valores de parâmetros de itens) precisam ter no máximo 100 caracteres para uma propriedade padrão do Google Analytics e 500 caracteres para uma propriedade do Google Analytics 360.

    Esse limite não se aplica aos parâmetros session_id e session_number quando os valores são fornecidos pelas variáveis incorporadas de ID da sessão do Analytics e número da sessão do Analytics no Gerenciador de Tags do Google.

  • Os parâmetros de itens podem ter no máximo 10 parâmetros personalizados.

  • O corpo da postagem precisa ter menos de 130 KB.

  • Eventos de app relacionados ao Measurement Protocol que são enviados ao Google Analytics não adicionam usuários de aplicativos para preencher os públicos-alvo de pesquisa no Google Ads.

Para outros requisitos de cada caso de uso, consulte Casos de uso comuns.