Enviar eventos do Measurement Protocol para o Google Analytics

Este guia explica como enviar Fluxo da Web e do app do Measurement Protocol do Google Analytics eventos para um servidor do Google Analytics. Assim, você pode conferir os eventos do Measurement Protocol na sua Relatórios do Google Analytics.

Escolha a plataforma a ser retratada neste guia:

Formatar a solicitação

O Measurement Protocol do Google Analytics é compatível apenas com 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 > Fluxos de dados > escolha seu fluxo > 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.

Confira a referência completa nos parâmetros de consulta.

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

  • client_id: identificador exclusivo de um cliente. Ele é diferente de um app_instance_id do Firebase. Use gtag.js('get').

  • user_id: opcional. Identificador exclusivo de um usuário. Pode conter somente UTF-8 caracteres. Para mais informações sobre esse identificador, consulte User-ID para análise multiplataforma.

  • consent: opcional. Saiba como definir as configurações de consentimento.

  • timestamp_micros: opcional. É a hora da época Unix, em microssegundos, para o eventos e propriedades do usuário na solicitação. Se não for especificado, o padrão será momento da solicitação.

  • events: matriz de itens de evento. Você pode incluir vários eventos em um solicitação.

    Para que a atividade do usuário seja mostrada em relatórios como o Relatório de tempo real, é necessário enviar engagement_time_msec e session_id como parte dos params para um event. O parâmetro engagement_time_msec precisa refletir o tempo de engajamento do evento em milissegundos.

    Veja um exemplo:

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "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 um evento tutorial_begin à Servidor de análise de dados:

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    events: [{
      name: 'tutorial_begin',
      params: {},
    }]
  })
});

Carimbo de data/hora da substituição

O Measurement Protocol usa o primeiro carimbo de data/hora 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. A hora 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 na solicitação. Como resultado, o Measurement Protocol atribui eventos tutorial_begin e join_group com 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 do evento carimbo de data/hora. Como resultado, o Measurement Protocol atribui o tutorial_begin um carimbo de data/hora de tutorialBeginUnixEpochTimeInMicros, e o evento join_group com 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 valores de parâmetros de itens, precisam ter 100 caracteres ou para uma propriedade padrão do Google Analytics e até 500 caracteres para 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.
  • Os eventos do Measurement Protocol do app enviados ao Google Analytics não preenchem a Pesquisa públicos-alvo no Google Ads para usuários de apps.

Para conferir os requisitos adicionais de cada caso de uso, consulte os casos de uso comuns.