Enviar eventos do Measurement Protocol para o Google Analytics

Este guia explica como enviar a um servidor do 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 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 uma nova chave secreta, navegue até Administrador > Coleta e modificação de dados > Fluxos de dados > escolha seu fluxo > Chaves secretas da API Measurement Protocol > Criar.

  • measurement_id: o ID de métricas associado a um fluxo, que fica na interface do Google Analytics, em Administrador > Fluxos de dados > escolha seu fluxo > ID de métricas.

    O measurement_id não é o ID do fluxo.

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

  {
   "client_id": "CLIENT_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 evento tutorial_begin e um evento join_group ao 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 measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

Substituir carimbo de data/hora

O Measurement Protocol usa o carimbo de data/hora primeiro que encontra na lista a seguir para cada evento na solicitação:

  1. O timestamp_micros do evento.
  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 na solicitação. Como resultado, o Measurement Protocol atribui aos eventos tutorial_begin e join_group um carimbo de data/hora de requestUnixEpochTimeInMicros.

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

O exemplo a seguir envia um carimbo de data/hora no nível da solicitação e outro no nível do evento. Como resultado, o Measurement Protocol atribui ao evento tutorial_begin um carimbo de data/hora de tutorialBeginUnixEpochTimeInMicros e ao evento join_group um carimbo de data/hora de requestUnixEpochTimeInMicros.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

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 de parâmetros, incluindo os de itens, precisam ter no máximo 100 caracteres em uma propriedade padrão do Google Analytics e 500 caracteres em uma propriedade do Google Analytics 360.
  • 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 apps para preencher os públicos-alvo de pesquisa no Google Ads.

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