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 Protocolo de Measurement 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. La clave de API de la IU de Google Analytics

Se encuentra en Administrador > Flujos de datos > Elige tu flujo > Protocolo de medición > Crear.

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

Cuerpo de POST en formato JSON

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. Es una marca de tiempo de Unix, en microsegundos, no en milisegundos. Representa la hora del evento. Debe configurarse 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 fecha anterior hasta 3 días calendario según la zona horaria de la propiedad.

user_properties

 object Opcional. Las propiedades del usuario para la medición

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 de la solicitud.

device

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

events[]

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

events[].name

 string Obligatorio. Nombre del evento. Consulta Eventos para ver todas las opciones.

events[].params

 object Opcional. Son los parámetros del evento. Consulta Eventos para ver los parámetros sugeridos para cada evento y Parámetros de eventos comunes.

Parámetros de eventos comunes

El Protocolo de medición tiene los siguientes parámetros de eventos comunes:

Clave Tipo Descripción

session_id

 number Es un número positivo que identifica la sesión del usuario. Se requiere para varios casos de uso comunes. Debe coincidir con la expresión regular ^\d+$.

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

Custom parameters

Puedes incluir parámetros personalizados centrados en el usuario, en el evento y en el elemento en una carga útil del Protocolo de Measurement.

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

Nombres de parámetros reservados

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

  • firebase_conversion

Los nombres de los 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_