Referência do Measurement Protocol

Esta página descreve o mecanismo de transporte e os parâmetros de dados do Measurement Protocol.

Transporte

Todos os dados precisam ser enviados com segurança usando solicitações POST HTTPS.

Envie solicitações para o seguinte endpoint:

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

Se você quiser que seus dados sejam processados na UE, use o seguinte endpoint:

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

Confira um exemplo de solicitação POST:

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

Substitua PAYLOAD_DATA pelo Payload da solicitação.

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

Payload

O payload tem duas partes:

  1. Parâmetros de consulta.
  2. Um corpo JSON POST.

Parâmetros de consulta

Nome do parâmetro Descrição

api_secret

 Obrigatório. A chave secreta da API na interface do Google Analytics.

Encontrado em Administrador > Fluxos de dados > Escolher seu fluxo > Measurement Protocol > Criar.

Particular para sua organização. Precisa ser atualizado regularmente para evitar excesso de spam.

Corpo de POST 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. Só pode incluir caracteres UTF-8.

timestamp_micros

 number

Opcional. Um carimbo de data/hora Unix, microssegundos, não milissegundos. Representa o horário do evento. Só pode ser definido para registrar eventos que aconteceram no passado. Pode ser substituído por 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. As propriedades do usuário para a medição.

user_data

 object Opcional. Dados fornecidos pelo usuário.
object Opcional. Configurações de consentimento para a solicitação. Consulte a seção de consentimento para mais informações.

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.

user_location

 object Opcional. Define as informações geográficas da solicitação em um formato estruturado.

ip_override

 string Opcional. Endereço IP que o Google Analytics usa para extrair informações geográficas da solicitação.

events[]

 array Obrigatório. Uma matriz de itens event. 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 Eventos para conferir todas as opções.

events[].params

 object Opcional. Parâmetros do evento. Consulte Eventos para conferir 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 vai usar as configurações de consentimento das transações on-line correspondentes para a instância do cliente ou app.

Chave Tipo Descrição

ad_user_data

 string

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

GRANTED ou DENIED.

ad_personalization

 string

Opcional. Consentimento para publicidade personalizada do usuário.

GRANTED ou DENIED.

Informações geográficas

Os atributos user_location e ip_override fornecem informações geográficas. user_location tem precedência sobre ip_override.

Esta é a estrutura do campo user_location. Inclua o maior número possível de atributos. Recomendamos country_id e region_id como mínimo.

Chave Tipo Descrição

city

 string Opcional. O nome da cidade.

region_id

 string Opcional. O país e a subdivisão ISO 3166. Por exemplo, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Opcional. O país no formato ISO 3166-1 alfa-2. Por exemplo, US, AU, ES, FR.

subcontinent_id

 string Opcional. O subcontinente no formato UN M49. Por exemplo, 011, 021, 030, 039.

continent_id

 string Opcional. O continente no formato UN M49. Por exemplo, 002, 019, 142, 150.

Confira um exemplo de user_location:

"user_location:" {
  "city:" "Mountain View",
  "region_id:" "US-CA",
  "country_id:" "US",
  "subcontinent_id:" "021",
  "continent_id:" "019"
}

ip_override é uma alternativa a user_location. Se você enviar ip_override, o Google Analytics vai derivar informações geográficas do endereço IP. Se você enviar user_location, o Google Analytics vai ignorar ip_override.

Se você não enviar user_location ou ip_override, o Google Analytics vai derivar informações geográficas de eventos de inclusão de tags usando client_id.

O Google Analytics aplica as configurações de dados de local granular da propriedade à solicitação, independentemente das informações geográficas enviadas.

Parâmetros personalizados

É possível 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 em user_properties.
  • Parâmetros personalizados no escopo do evento podem ser incluídos em events[].params.
  • Parâmetros personalizados no escopo do item podem ser incluídos em items.

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

Nomes reservados

Alguns nomes de eventos, parâmetros e propriedades do usuário são reservados e não podem ser usados:

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

Os nomes de parâmetro 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 estã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, os nomes das propriedades do usuário não podem começar com:

  • _ (underscore)
  • firebase_
  • ga_
  • google_