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 para o Google Analytics 4 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 > 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 caracteres UTF-8. Para mais informações sobre esse identificador, consulte User-ID para análise em várias plataformas.

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

  • events: matriz de itens de evento. É possível incluir vários eventos em uma única 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 ao servidor do Google Analytics:

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: {},
    }]
  })
});

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.
  • Os parâmetros de itens podem ter no máximo 10 parâmetros personalizados.
  • O corpo da postagem precisa ter menos de 130 KB.
  • A atribuição de eventos do Measurement Protocol funciona até 63 dias após o evento on-line de inclusão de tag mais recente para exportação de conversões ao Google Ads e outras integrações de mídia, mesmo que a janela de conversão do evento seja maior do que 63 dias. Já a atribuição para esses eventos funciona durante toda a janela de conversão.
  • Em atividades de remarketing, é possível combinar eventos do Measurement Protocol pelo total de dias a seguir após o evento on-line mais recente com um cookie ou ID do dispositivo associado:
    • Fluxo da Web: 30 dias
    • Fluxo do app: 42 dias
  • Eventos de app relacionados ao Measurement Protocol que são enviados ao Google Analytics 4 não adicionam usuários de apps para preencher os públicos-alvo de pesquisa no Google Ads.