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

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 por 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 JSON POST.

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.

firebase_app_id

 Obrigatório. ID do app do Firebase. O identificador de um app do Firebase.

Encontrado no Console do Firebase em Configurações do projeto > Geral > Seus apps > ID do app.

Corpo da postagem JSON

O tamanho do corpo da postagem JSON precisa ser menor que 130 KB.

Chave Tipo Descrição

app_instance_id

 string Obrigatório. Identificador exclusivo de uma instalação específica de um app do Firebase.

Não é o mesmo que um client_id da Web.

Precisa ser recuperado usando o SDK do Firebase:

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. É possível enviar até 25 propriedades do usuário por solicitação. Os nomes das propriedades do usuário podem ter, no máximo, 24 caracteres, e os valores, no máximo, 36.

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 ver os eventos recomendados.

events[].name

 string Obrigatório. Nome do evento. Os nomes de eventos precisam ter até 40 caracteres. Consulte Eventos para ver os eventos recomendados.

events[].params

 object Opcional. Parâmetros do evento. Até 25 parâmetros podem ser enviados por evento. Consulte Eventos para ver os parâmetros recomendados de cada evento e Parâmetros de evento comuns.

Os nomes de parâmetros precisam ter no máximo 40 caracteres. Os valores de parâmetros precisam ter no máximo 100 caracteres para uma propriedade padrão do Google Analytics e 500 caracteres para uma propriedade do Google Analytics 360.

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

Precisa ser recuperado usando o SDK do Firebase:

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 ao Google dados do usuário dos eventos e propriedades do usuário da solicitação 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 maior número 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 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 tag usando app_instance_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"
}
Se uma solicitação não especificar o device, o Google Analytics vai derivar as informações do dispositivo dos eventos de inclusão de tags usando app_instance_id.

Independente de você especificar device, 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 Measurement Protocol 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-o como ENFORCE_RECOMMENDATIONS.

Parâmetros personalizados

Você pode incluir parâmetros personalizados no escopo do usuário, no escopo do evento e no escopo 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 fluxos 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_