Referência do Measurement Protocol

Nesta página, descrevemos o mecanismo de transporte e os parâmetros de dados do protocolo de medição.

Transporte

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

Envie solicitações para o seguinte endpoint:

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

Se você quiser que seus dados sejam coletados na UE, use o seguinte endpoint em vez disso:

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 retorna um código de status 2xx se a solicitação HTTP for recebida. O Measurement Protocol não retorna um código de erro se o payload estiver incorreto ou se os dados estiverem errados ou não forem processados pelo Google Analytics.

Payload

O payload tem duas partes:

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

Parâmetros de consulta

Nome do parâmetro Descrição

api_secret

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

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

Privado para sua organização. Precisa ser atualizado 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. Pode incluir apenas caracteres UTF-8.

timestamp_micros

 number

Opcional. Um carimbo de data/hora do 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é 72 horas.

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. 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.

user_location

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

ip_override

 string Opcional. Endereço IP usado pelo Google Analytics para derivar informações geográficas da solicitação.

device

 object Opcional. Define as informações do dispositivo para a solicitação em um formato estruturado.

validation_behavior

 string

Opcional. Define o comportamento de validação da solicitação.

RELAXED ou ENFORCE_RECOMMENDATIONS. O padrão é RELAXED se não for especificado.

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 todas as opções.

events[].params

 object Opcional. Parâmetros do evento. Confira os parâmetros sugeridos para cada evento e os parâmetros comuns de eventos.

Parâmetros de evento comuns

O Measurement Protocol tem os seguintes parâmetros de evento comuns:

Chave Tipo Descrição

session_id

 number Um número positivo que identifica a sessão do usuário. Necessário para vários casos de uso comuns. Precisa corresponder à expressão regular ^\d+$.

engagement_time_msec

 number A duração do engajamento do usuário, em milissegundos, para o evento. Use um valor que reflita a quantidade de tempo de engajamento do usuário desde o evento anterior.

timestamp_micros

 number O horário da época Unix, em microssegundos, do evento. Use esse parâmetro para substituir o carimbo de data/hora do 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. Consentimento para enviar dados do usuário dos eventos e propriedades do usuário da solicitação ao Google para fins de publicidade.

GRANTED ou DENIED.

ad_personalization

 string

Opcional. Consentimento para publicidade personalizada para o 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. Forneça o máximo possível de atributos. Recomendamos country_id e region_id, no mínimo.

Chave Tipo Descrição

city

 string Opcional. O nome da cidade. Se a cidade for nos EUA, defina também country_id e region_id para que o Google Analytics possa mapear corretamente o nome da cidade para um ID 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 M49 da ONU. 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 tag usando client_id.

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

Informações do dispositivo

Para enviar informações do dispositivo, use o campo device. Esta é a estrutura do campo device. Forneça o máximo possível de atributos. Recomendamos pelo menos category.

Chave Tipo Descrição

category

 string Opcional. A categoria do dispositivo. Por exemplo: desktop, tablet, mobile, smart TV.

language

 string Opcional. O idioma no formato ISO 639-1. Por exemplo, en, en-US.

screen_resolution

 string Opcional. A resolução do dispositivo, formatada como WIDTHxHEIGHT. Por exemplo, 1280x2856, 1080x2340.

operating_system

 string Opcional. O sistema operacional ou a plataforma. Por exemplo, MacOS.

operating_system_version

 string Opcional. A versão do sistema operacional ou da plataforma. Por exemplo, 13.5.

model

 string Opcional. O modelo do dispositivo. Por exemplo, Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Opcional. A marca do dispositivo. Por exemplo, Google, Samsung.

browser

 string Opcional. A marca ou o tipo de navegador. Por exemplo, Chrome, Firefox.

browser_version

 string Opcional. A versão do navegador. Por exemplo, 136.0.7103.60, 5.0.

O snippet a seguir mostra um exemplo de configurações de device:

"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"
}

Independente de você especificar o Google Analytics aplica as configurações de dados granulares de dispositivos da propriedade à solicitação.

Comportamento da validação

O atributo validation_behavior controla como o Measurement Protocol valida o conteúdo da solicitação.

  • A validação RELAXED só rejeita solicitações malformadas. Ele ainda pode aceitar eventos e parâmetros com nomes de campo inválidos ou com dados que não são do tipo correto, mas ignora parâmetros que excedem os limites. O Protocolo de medição usa a validação RELAXED por padrão.
  • A validação do ENFORCE_RECOMMENDATIONS rejeita parâmetros de evento e item que não são do tipo correto ou que excedem os limites. Além disso, ENFORCE_RECOMMENDATIONS rejeita qualquer evento ou propriedade do usuário com um carimbo de data/hora que não esteja nas últimas 72 horas.

Recomendamos a seguinte abordagem:

  • Use ENFORCE_RECOMMENDATIONS ao validar eventos para receber o máximo de feedback possível sobre possíveis problemas com suas solicitações.

    Também é possível validar solicitações usando o Criador de eventos, já que ele especifica ENFORCE_RECOMMENDATIONS ao validar solicitações.

  • Não especifique validation_behavior ao enviar eventos para minimizar os dados rejeitados pelo Measurement Protocol.

    Se você quiser priorizar a validação estrita em vez da coleta de dados ao enviar uma solicitação específica, adicione o campo validation_behavior e defina como ENFORCE_RECOMMENDATIONS.

Parâmetros personalizados

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 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
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Além disso, os eventos ad_impression, in_app_purchase e screen_view são permitidos apenas para streams de apps.

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âmetros não podem começar com o seguinte:

  • _ (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, os nomes das propriedades do usuário não podem começar com:

  • _ (underscore)
  • firebase_
  • ga_
  • google_