Referencia del Protocolo de medición

En esta página, se describen el mecanismo de transporte y los parámetros de datos del Protocolo de Measurement.

Transporte

Todos los datos deben enviarse de forma segura con solicitudes POST HTTPS.

Envía solicitudes al siguiente extremo:

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

Si deseas que se recopilen tus datos en la UE, usa el siguiente extremo:

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

A continuación, se muestra una solicitud de POST de ejemplo:

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

Reemplaza PAYLOAD_DATA por la carga útil de la solicitud.

El Measurement Protocol devuelve un código de estado 2xx si se recibe la solicitud de HTTP. El Protocolo de Measurement no devuelve un código de error si la carga útil no tiene el formato correcto o si los datos son incorrectos o no los procesa Google Analytics.

Carga útil

La carga útil tiene dos partes:

  1. Son los parámetros de consulta.
  2. Un cuerpo POST JSON.

Parámetros de consulta

Nombre del parámetro Descripción

api_secret

 Obligatorio. El secreto de API de la IU de Google Analytics

Se encuentra en Administrador > Flujos de datos > Elige tu flujo > Measurement Protocol > Crear.

Es privada para tu organización. Debe actualizarse periódicamente para evitar el SPAM excesivo.

Cuerpo de POST en formato JSON

El tamaño del cuerpo de la solicitud POST en formato JSON debe ser inferior a 130 KB.

Clave Tipo Descripción

user_id

 string

Opcional. Es un identificador único para un usuario. Consulta User-ID para el análisis multiplataforma para obtener más información sobre este identificador. Solo puede incluir caracteres UTF-8.

timestamp_micros

 number

Opcional. Una marca de tiempo de Unix, en microsegundos, no en milisegundos. Representa la hora del evento. Debe establecerse solo para registrar eventos que ocurrieron en el pasado. Se puede anular con user_property o marcas de tiempo de eventos. Los eventos se pueden registrar con una fecha anterior de hasta 72 horas.

user_properties

 object Opcional. Las propiedades del usuario para la medición Se pueden enviar hasta 25 propiedades del usuario por solicitud. Los nombres de las propiedades del usuario deben tener 24 caracteres o menos, y los valores de las propiedades del usuario deben tener 36 caracteres o menos.

user_data

 object Opcional. Datos proporcionados por el usuario.
object Opcional. Es la configuración del consentimiento para la solicitud. Consulta la sección de consentimiento para obtener más información.

non_personalized_ads

 boolean Opcional. Se establece en true para indicar que los datos del usuario no se deben usar para los anuncios personalizados.

user_location

 object Opcional. Establece la información geográfica de la solicitud en un formato estructurado.

ip_override

 string Opcional. Dirección IP que usa Google Analytics para obtener información geográfica para la solicitud.

device

 object Opcional. Establece la información del dispositivo para la solicitud en un formato estructurado.

validation_behavior

 string

Opcional. Establece el comportamiento de validación para la solicitud.

RELAXED o ENFORCE_RECOMMENDATIONS El valor predeterminado es RELAXED si no se especifica.

events[]

 array Obligatorio. Es un array de elementos event. Se pueden enviar hasta 25 eventos por solicitud. Consulta la referencia de eventos para ver los eventos recomendados.

events[].name

 string Obligatorio. Nombre del evento. Los nombres de los eventos deben tener 40 caracteres o menos. Consulta Eventos para ver los eventos recomendados.

events[].params

 object Opcional. Son los parámetros del evento. Se pueden enviar hasta 25 parámetros por evento. Consulta Eventos para conocer los parámetros recomendados para cada evento y Parámetros de eventos comunes.

Los nombres de los parámetros deben tener 40 caracteres o menos. Los valores de los parámetros deben tener 100 caracteres o menos para una propiedad estándar de Google Analytics y 500 caracteres o menos para una propiedad de Google Analytics 360.

Parámetros de eventos comunes

El Measurement Protocol tiene los siguientes parámetros de eventos comunes:

Clave Tipo Descripción

session_id

engagement_time_msec

 number Es la duración de la participación del usuario, en milisegundos, para el evento. Usa un valor que refleje la cantidad de tiempo de participación del usuario desde el evento anterior.

timestamp_micros

 number Es la hora de Unix en microsegundos para el evento. Usa este parámetro para anular la marca de tiempo del evento.

El atributo consent configura los tipos y estados de consentimiento. Si no especificas consent, Google Analytics usa la configuración de consentimiento de las interacciones en línea correspondientes para el cliente o la instancia de aplicación.

Clave Tipo Descripción

ad_user_data

 string

Opcional. Es el consentimiento para enviar a Google los datos del usuario de los eventos y las propiedades del usuario de la solicitud con fines publicitarios.

GRANTED o DENIED

ad_personalization

 string

Opcional. Es el consentimiento para la publicidad personalizada del usuario.

GRANTED o DENIED

Información geográfica

Los atributos user_location y ip_override proporcionan información geográfica. user_location tiene prioridad sobre ip_override.

Esta es la estructura del campo user_location. Proporciona la mayor cantidad posible de atributos. Recomendamos country_id y region_id como mínimo.

Clave Tipo Descripción

city

 string Opcional. El nombre de la ciudad. Si la ciudad se encuentra en EE.UU., también debes configurar country_id y region_id para que Google Analytics pueda asignar correctamente el nombre de la ciudad a un ID de ciudad.

region_id

 string Opcional. País y subdivisión según la norma ISO 3166. Por ejemplo, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Opcional. Es el país en formato ISO 3166-1 alpha-2. Por ejemplo, US, AU, ES y FR.

subcontinent_id

 string Opcional. Subcontinente en formato UN M49. Por ejemplo, 011, 021, 030, 039.

continent_id

 string Opcional. Es el continente en formato UN M49. Por ejemplo, 002, 019, 142, 150.

Aquí tienes un ejemplo de user_location:

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

ip_override es una alternativa a user_location. Si envías ip_override, Google Analytics obtendrá información geográfica de la dirección IP. Si envías user_location, Google Analytics ignorará ip_override.

Si no envías user_location o ip_override, Google Analytics deriva la información geográfica de los eventos de etiquetado con client_id.

Google Analytics aplica la configuración de datos de ubicación detallados de la propiedad a la solicitud, independientemente de la información geográfica que se envíe.

Información del dispositivo

Para enviar información del dispositivo, usa el campo device. Esta es la estructura del campo device. Proporciona la mayor cantidad posible de atributos. Recomendamos category como mínimo.

Clave Tipo Descripción

category

 string Opcional. Es la categoría del dispositivo. Por ejemplo: desktop, tablet, mobile, smart TV.

language

 string Opcional. Idioma en formato ISO 639-1. Por ejemplo, en, en-US.

screen_resolution

 string Opcional. Resolución del dispositivo, con el formato WIDTHxHEIGHT. Por ejemplo, 1280x2856, 1080x2340.

operating_system

 string Opcional. Es el sistema operativo o la plataforma. Por ejemplo, MacOS.

operating_system_version

 string Opcional. Es la versión del sistema operativo o la plataforma. Por ejemplo, 13.5.

model

 string Opcional. Modelo del dispositivo Por ejemplo: Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Opcional. Marca del dispositivo Por ejemplo: Google, Samsung.

browser

 string Opcional. Marca o tipo de navegador Por ejemplo: Chrome, Firefox.

browser_version

 string Opcional. Es la versión del navegador. Por ejemplo: 136.0.7103.60, 5.0.

En el siguiente fragmento, se muestra un ejemplo de la configuración 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"
}

Independientemente de si especificas,, Google Analytics aplica la configuración de datos detallados del dispositivo de la propiedad a la solicitud.

Comportamiento de la validación

El atributo validation_behavior controla cómo el Protocolo de medición valida el contenido de la solicitud.

  • La validación de RELAXED solo rechaza las solicitudes con formato incorrecto. Es posible que siga aceptando eventos y parámetros con nombres de campos no válidos o con datos que no sean del tipo correcto, pero ignora los parámetros que superan los límites. El Measurement Protocol usa la validación de RELAXED de forma predeterminada.
  • La validación de ENFORCE_RECOMMENDATIONS rechaza los parámetros de eventos y elementos que no son del tipo correcto o que contienen parámetros que superan los límites. Además, ENFORCE_RECOMMENDATIONS rechaza cualquier evento o propiedad del usuario con una marca de tiempo que no se encuentre dentro de las últimas 72 horas.

Te recomendamos que sigas este enfoque:

  • Usa ENFORCE_RECOMMENDATIONS cuando valides eventos para obtener la mayor cantidad de comentarios posible sobre los problemas potenciales con tus solicitudes.

    También puedes validar solicitudes con el Creador de eventos, ya que especifica ENFORCE_RECOMMENDATIONS cuando valida solicitudes.

  • No especifiques validation_behavior cuando envíes eventos para minimizar los datos rechazados por Measurement Protocol.

    Si deseas priorizar la validación estricta por sobre la recopilación de datos cuando envías una solicitud en particular, agrega el campo validation_behavior y configúralo como ENFORCE_RECOMMENDATIONS.

Parámetros personalizados

Puedes incluir parámetros personalizados con alcance de usuario, con alcance de evento y con alcance de artículo en una carga útil del Measurement Protocol.

  • Los parámetros personalizados centrados en el usuario se pueden incluir en user_properties.
  • Se pueden incluir parámetros personalizados centrados en el evento en events[].params.
  • Se pueden incluir parámetros personalizados centrados en el artículo en items.

Algunos eventos tienen parámetros recomendados. Consulta eventos para conocer los parámetros recomendados para todos los eventos admitidos.

Nombres reservados

Algunos nombres de eventos, parámetros y propiedades del usuario están reservados y no se pueden usar:

Nombres de eventos reservados

Los siguientes nombres de eventos están reservados y no se pueden utilizar:

  • 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

Además, los eventos ad_impression, in_app_purchase y screen_view solo se permiten para los flujos de aplicaciones.

Nombres de parámetros reservados

Los siguientes nombres de parámetros están reservados y no se pueden utilizar:

  • firebase_conversion

Los nombres de parámetros no pueden comenzar con lo siguiente:

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

Nombres de propiedades del usuario reservados

Los siguientes nombres de propiedades del usuario están reservados y no se pueden utilizar:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Además, los nombres de propiedades del usuario no pueden comenzar con lo siguiente:

  • _ (underscore)
  • firebase_
  • ga_
  • google_