Referência do Measurement Protocol

Visão geral

O envio de dados ao Google Analytics com o Measurement Protocol consiste em duas partes:

  1. Transporte: para onde e como você envia os dados.
  2. Payload: os dados que você envia.

Neste documento, descrevemos como o transporte e o payload são formatados.

Transporte

Endpoint do URL

Você envia dados pelo Measurement Protocol fazendo solicitações POST HTTP para o seguinte endpoint:

https://www.google-analytics.com/mp/collect

Para transmitir um evento, envie a seguinte solicitação POST:

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

  • O BODY da solicitação. Consulte Payload.

Códigos de resposta

O Measurement Protocol sempre retornará um código de status 2xx se a solicitação HTTP tiver sido recebida. O Measurement Protocol não vai retornar um código de erro se os dados de payload tiverem a formatação incorreta, se estiverem errados ou não tiverem sido processados pelo Google Analytics.

Payload

O envio dos dados ao Google Analytics pelo Measurement Protocol ocorre em duas etapas:

  1. Parâmetros de consulta
  2. Corpo JSON POST

Parâmetros de consulta

Nome do parâmetro Descrição

api_secret

Obrigatório. Uma API Secret gerada na interface do Google Analytics.

Para criar um novo secret, navegue na interface do Google Analytics até:
Administrador > Fluxos de dados > escolha seu fluxo > Measurement Protocol > Criar

Recomendamos que você mantenha essas informações privadas na sua organização. Se você implantar o Measurement Protocol no lado do cliente, alterne api_secrets regularmente para evitar excesso de spam.

Corpo da postagem JSON

Chave Tipo Descrição

user_id

 string

Opcional. Identificador exclusivo de um usuário. Para mais informações sobre esse identificador, consulte User-ID para análise multiplataforma.

timestamp_micros

 number

Opcional. Carimbo de data/hora Unix (em microssegundos) para o horário a ser associado ao evento. Só pode ser definido para registrar eventos que aconteceram no passado. Esse valor pode ser modificado com user_property ou carimbos de data/hora de eventos. Os eventos podem ser atualizados em até três dias corridos com base no fuso horário da propriedade.

user_properties

 object Opcional. Propriedades do usuário para a medição. Consulte Propriedades do usuário para mais informações.

user_data

 object Opcional. Dados fornecidos pelo usuário. Consulte o guia de dados fornecidos pelo usuário para mais informações.
object Opcional. Define as configurações de consentimento para a solicitação. Confira a seção de consentimento para saber mais.

non_personalized_ads

 boolean Opcional. Defina como true para indicar que os dados do usuário não podem ser usados para anúncios personalizados.

events[]

 array Obrigatório. Matriz de itens de evento. Até 25 eventos podem ser enviados por solicitação. Consulte a referência de eventos para todos os eventos válidos.

events[].name

 string Obrigatório. Nome do evento. Consulte a referência de eventos para todas as opções.

events[].params

 object Opcional. Parâmetros do evento. Confira os parâmetros sugeridos para cada evento.

O atributo consent configura os tipos e estados de consentimento. Se você não especificar consent, o Google Analytics usará as configurações de consentimento das transações on-line correspondentes para a instância do cliente ou aplicativo.

Chave Tipo Descrição

ad_user_data

 string

Opcional. Define o consentimento para enviar dados do usuário dos eventos e das propriedades do usuário da solicitação ao Google para fins de publicidade.

Precisa ser GRANTED ou DENIED.

ad_personalization

 string

Opcional. Define o consentimento para veicular publicidade personalizada para o usuário.

Precisa ser GRANTED ou DENIED.

Parâmetros personalizados

Além dos parâmetros prescritos, você pode incluir parâmetros personalizados no escopo do usuário, do evento e do item em um payload do Measurement Protocol.

  • Parâmetros personalizados no escopo do usuário podem ser incluídos no objeto user_properties do payload.
  • Parâmetros personalizados no escopo do evento podem ser incluídos no objeto events[].params do payload.
  • Parâmetros personalizados no escopo do item podem ser incluídos na matriz items de cada evento.

Alguns eventos têm parâmetros recomendados. Consulte eventos e veja os parâmetros recomendados para todos os eventos compatíveis.

Nomes reservados

Nomes de eventos reservados

Os nomes de evento a seguir estão reservados e não podem ser usados:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Nomes de parâmetros reservados

Os nomes de parâmetro a seguir estão reservados e não podem ser usados:

  • firebase_conversion

Além disso, eles não podem começar com:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Nomes de propriedades do usuário reservados

Os seguintes nomes de propriedades do usuário são reservados e não podem ser usados:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Além disso, eles não podem começar com:

  • _ (underscore)
  • firebase_
  • ga_
  • google_