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 de Measurement Protocol de Google Analytics a un servidor de Google Analytics para que puedas verlos en tus informes de Google Analytics.

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

Firebase gtag.js

Da formato a la solicitud

Measurement Protocol de Google Analytics solo admite solicitudes POST de HTTP.

Para enviar un evento, usa el siguiente formato:

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

PAYLOAD_DATA

Sugerencia: Si quieres que tus datos se recopilen en la UE, cambia el HOST del ejemplo por region1.google-analytics.com.

Debes proporcionar lo siguiente en la URL de la solicitud:

• api_secret: El SECRETO DE LA API generado en la IU de Google Analytics.

  Para crear un secreto nuevo, navega a Administrador > Recopilación y modificación de datos > Flujos de datos > elige tu flujo > Secretos de la API de Measurement Protocol > Crear.

• firebase_app_id: El ID de la aplicación de Firebase, que se encuentra en Firebase console en Configuración del proyecto > General > Tus apps > ID de la app.

  El firebase_app_id no es lo mismo que el app_instance_id. El firebase_app_id identifica tu app, mientras que app_instance_id identifica una sola instalación de la app.

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

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

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

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 la aplicación en Objetos o archivos de configuración de Firebase.

Anula la marca de tiempo

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

1. El timestamp_micros del evento o la propiedad del usuario
2. El timestamp_micros de la solicitud
3. La hora en que Measurement Protocol 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 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ía 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, Measurement Protocol 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 y propiedades del usuario anteriores

Los eventos y las propiedades del usuario se pueden retrotraer 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 no se establece validation_behavior o se establece en RELAXED, Measurement Protocol acepta el evento o la propiedad del usuario, pero anula su marca de tiempo a 72 horas.
• Si validation_behavior se establece en ENFORCE_RECOMMENDATIONS, Measurement Protocol rechaza el evento o la propiedad del usuario.

Los eventos enviados con Measurement Protocol que se deben 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 desde la marca de tiempo original del evento del cliente. Es posible que los eventos recibidos más tarde no se procesen como se espera, en particular 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:

Nota: Para obtener información sobre las limitaciones de las funciones de 360, consulta Google Analytics 360.

• 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 del parámetro del elemento, deben tener 100 caracteres o menos para una propiedad de Google Analytics estándar 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 con las variables integradas correspondientes de 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 la aplicación que se envían a Google Analytics no propagan las audiencias de búsqueda en Google Ads para los usuarios de la aplicación.

• 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 son puntos comunes de confusión:

• screen_view: Este evento solo se permite para los flujos de aplicaciones. Para los flujos web, usa page_view en su lugar.
• ad_impression: Este evento solo se permite para los flujos de aplicaciones.
• in_app_purchase: Este evento solo se permite para los flujos de aplicaciones. Para los flujos web, usa el purchase evento en su lugar.

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