Envía eventos del Protocolo de medición a Google Analytics

En esta guía, se explica cómo puedes enviar eventos de flujos web y de aplicaciones del Protocolo de medición de Google Analytics a un servidor de Google Analytics para que puedas ver los eventos del Protocolo de medición en tus informes de Google Analytics.

Los identificadores y parámetros necesarios para las solicitudes de Measurement Protocol dependen de si envías eventos a un flujo web o a un flujo de aplicaciones.

  • En el caso de los flujos web (que suelen instrumentarse con gtag.js o Google Tag Manager), se usa measurement_id en la URL de la solicitud y client_id en el cuerpo JSON para identificar la instancia del usuario. El client_iddebe coincidir con el ID que genera la etiqueta de Google Analytics en tu sitio web.
  • En el caso de los flujos de aplicaciones (instrumentados con el SDK de Firebase), se usa firebase_app_id en la URL de la solicitud y app_instance_id en el cuerpo JSON, que proporciona el SDK de Google Analytics para Firebase.

En esta guía, se proporcionan ejemplos para ambas situaciones.

Componentes clave de la solicitud por tipo de transmisión

Componente Flujo web (gtag.js/GTM) Flujo de aplicación (Firebase)
Parámetro de URL del flujo de datos measurement_id firebase_app_id
Parámetro de URL del secreto de API Obligatorio Obligatorio
Campo del cuerpo JSON del ID del dispositivo client_id app_instance_id

Elige la plataforma que quieres ver en esta guía:

En esta pestaña, se muestran instrucciones para enviar eventos desde tu servidor que se correlacionan con la actividad del usuario en un flujo de aplicación con el SDK de Google Analytics para Firebase. Ten en cuenta que estas solicitudes usan firebase_app_id y app_instance_id.

Requisitos previos

Para enviar eventos con el Protocolo de medición, necesitas identificadores específicos de tu propiedad de Google Analytics o proyecto de Firebase.

Secreto de API

El api_secret se usa para autenticar tus solicitudes. Es fundamental mantener este secreto confidencial.

Para crear un secreto nuevo, haz lo siguiente:

  1. Ve a Google Analytics y navega a tu cuenta y propiedad.
  2. Haz clic en Administrador en la esquina inferior izquierda.
  3. En Recopilación y modificación de datos, haz clic en Flujos de datos.
  4. Selecciona tu flujo de datos web o de la aplicación.
  5. Haz clic en Secretos de API de Measurement Protocol.
  6. Haz clic en Crear.
  7. Ingresa un sobrenombre para el secreto y haz clic en Crear.

  8. Copia el valor del secreto.

ID de la app de Firebase

El firebase_app_id identifica tu app de Firebase. No es lo mismo que el app_instance_id.

Para encontrar el ID de tu app de Firebase, sigue estos pasos:

  1. Abre tu proyecto en Firebase console.
  2. Haz clic en el ícono de ajustes junto a Project Overview y selecciona Configuración del proyecto.
  3. En la pestaña General, ve a la sección Tus apps.
  4. Selecciona la app específica para iOS o Android.
  5. Copia el valor del ID de la app.

Cómo dar formato a la solicitud

El Protocolo de medición de Google Analytics solo admite solicitudes POST HTTP.

Para enviar un evento, usa el siguiente formato:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

Debes proporcionar lo siguiente en los parámetros de consulta de la URL de la solicitud (consulta Requisitos previos para obtener detalles sobre cómo encontrar o crear estos valores):

  • api_secret: Es el secreto de API para autenticar la solicitud.
  • firebase_app_id: Es el ID de la app de Firebase de tu aplicación.

Debes proporcionar un cuerpo de solicitud en el formato de cuerpo POST de JSON para el Protocolo de Measurement. Por ejemplo:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Debes proporcionar app_instance_id en el cuerpo de la solicitud para identificar una instalación única de tu app para dispositivos móviles. Ten en cuenta que este valor es diferente de firebase_app_id, que identifica la app en sí. Si deseas obtener más información sobre el parámetro app_instance_id y cómo recuperarlo con el SDK de Firebase, consulta la documentación de referencia de app_instance_id.

Si bien session_start es un nombre de evento reservado, crear un nuevo session_id crea una nueva sesión sin necesidad de enviar session_start. Comprende cómo se registran las sesiones.

Probar

Este es un ejemplo que puedes usar para enviar varios eventos a la vez. En este ejemplo, se envían un evento tutorial_begin y un evento join_group a tu servidor de Google Analytics, se incluye información geográfica con el campo user_location y se incluye información del dispositivo con el campo device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    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"
    }
  })
});

El formato de firebase_app_id es específico de la plataforma. Consulta ID de aplicación en Objetos o archivos de configuración de Firebase.

Anular marca de tiempo

Measurement Protocol usa la primera marca de tiempo first que encuentra en la siguiente lista para cada evento y propiedad del usuario en la solicitud:

  1. Es el timestamp_micros del evento o la propiedad del usuario.
  2. Es el timestamp_micros de la solicitud.
  3. Es la fecha y hora en que el Protocolo de medición recibe la solicitud.

En el siguiente ejemplo, se envía una marca de tiempo a nivel de la solicitud que se aplica a todos los eventos y las propiedades del usuario de la solicitud. Como resultado, Measurement Protocol asigna una marca de tiempo de requestUnixEpochTimeInMicros a los eventos tutorial_begin y join_group, y a la propiedad del usuario customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

En el siguiente ejemplo, se envían una marca de tiempo a nivel de la solicitud, una marca de tiempo a nivel del evento y una marca de tiempo a nivel de la propiedad del usuario. Como resultado, el Protocolo de Measurement asigna las siguientes marcas de tiempo:

  • tutorialBeginUnixEpochTimeInMicros para el evento tutorial_begin
  • customerTierUnixEpochTimeInMicros para la propiedad del usuario customer_tier
  • requestUnixEpochTimeInMicros para el evento join_group y la propiedad del usuario newsletter_reader
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Comportamiento de validación para eventos pasados y propiedades del usuario

Los eventos y las propiedades del usuario se pueden registrar con una fecha anterior de hasta 72 horas. Si el valor de timestamp_micros es anterior a 72 horas, Measurement Protocol acepta o rechaza el evento o la propiedad del usuario de la siguiente manera:

  • Si validation_behavior no está configurado o se configura como RELAXED, el Protocolo de Measurement acepta el evento o la propiedad del usuario, pero anula su marca de tiempo y la establece en hace 72 horas.
  • Si el valor de validation_behavior se establece en ENFORCE_RECOMMENDATIONS, Measurement Protocol rechaza el evento o la propiedad del usuario.

Los eventos enviados con el Protocolo de medición que se pretenden unir o procesar junto con los eventos recopilados por el SDK de Google Analytics para Firebase o gtag.js deben recibirse en Google Analytics en un plazo de 48 horas a partir de la marca de tiempo original del evento del cliente. Es posible que los eventos que se reciban después de esta fecha no se procesen según lo previsto, en especial para fines como la atribución de conversiones.

Limitaciones

Se aplican las siguientes limitaciones al envío de eventos de Measurement Protocol a Google Analytics:

  • Puedes enviar como máximo 100 millones de solicitudes que no son de conversión por hora para cada propiedad. Una solicitud es una solicitud sin conversión si ninguno de los eventos de la solicitud es un evento clave para el que hay una conversión en Google Ads. Si superas este límite, el Protocolo de Measurement ignorará de forma silenciosa todas las solicitudes que no sean de conversión para la propiedad durante el resto de la hora.

  • Las solicitudes pueden tener un máximo de 25 eventos.

  • Los eventos pueden tener un máximo de 25 parámetros.

  • Los eventos pueden tener un máximo de 25 propiedades del usuario.

  • Los nombres de las propiedades del usuario deben tener 24 caracteres o menos.

  • Los valores de propiedad del usuario deben tener 36 caracteres o menos.

  • Los nombres de eventos deben tener 40 caracteres o menos, solo pueden contener caracteres alfanuméricos y guiones bajos, y deben comenzar con un carácter alfabético.

  • Los nombres de parámetros, incluidos los parámetros de elementos, deben tener 40 caracteres o menos, solo pueden contener caracteres alfanuméricos y guiones bajos, y deben comenzar con un carácter alfabético.

  • Los valores de los parámetros, incluidos los valores de los parámetros del elemento, 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.

    Este límite no se aplica a los parámetros session_id y session_number cuando sus valores se proporcionan a través de las variables integradas correspondientes ID de sesión de Analytics y Número de sesión de Analytics en Google Tag Manager.

  • Los parámetros de elementos pueden tener un máximo de 10 parámetros personalizados.

  • El cuerpo de la publicación debe ser inferior a 130 KB.

  • Los eventos de Measurement Protocol de medición de apps enviados a Google Analytics no completan los públicos de la Búsqueda en Google Ads para los usuarios de aplicaciones.

  • Algunos nombres de eventos, parámetros y propiedades del usuario están reservados y no se pueden usar. Consulta Nombres reservados para obtener más detalles.

Nombres reservados

Measurement Protocol tiene varios nombres reservados que no se pueden usar para eventos, parámetros ni propiedades del usuario.

Los siguientes nombres de eventos suelen generar confusión:

Para conocer los requisitos adicionales de cada caso de uso, consulta los casos de uso comunes.