Envoyer des événements du protocole de mesure à Google Analytics

Ce guide explique comment envoyer des événements de flux Web et d'application du protocole de mesure Google Analytics à un serveur Google Analytics. Vous pourrez ainsi consulter les événements du protocole de mesure dans vos rapports Google Analytics.

Choisissez la plate-forme que vous souhaitez voir dans ce guide :

Mise en forme de la requête

Le protocole de mesure Google Analytics n'accepte que les requêtes HTTP POST.

Pour envoyer un événement, utilisez le format suivant :

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

PAYLOAD_DATA

Vous devez fournir les éléments suivants dans l'URL de la requête :

  • api_secret : code secret de l'API généré dans l'UI Google Analytics.

    Pour créer un secret, accédez à Administration > Collecte et modification des données > Flux de données > choisissez votre flux > Secrets de l'API Measurement Protocol > Créer.

  • measurement_id : ID de mesure associé à un flux, que vous trouverez dans l'UI Google Analytics sous Administration > Flux de données > choisissez votre flux > ID de mesure.

    measurement_id n'est pas votre ID de flux.

Vous devez fournir un corps de requête au format corps POST JSON pour le protocole de mesure. Exemple :

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

Même si session_start est un nom d'événement réservé, créer un session_id génère une nouvelle session sans qu'il soit nécessaire d'envoyer session_start. Découvrez comment les sessions sont comptabilisées.

Essayer

Voici un exemple que vous pouvez utiliser pour envoyer plusieurs événements à la fois. Cet exemple envoie un événement tutorial_begin et un événement join_group à votre serveur Google Analytics. Il inclut des informations géographiques à l'aide du champ user_location et des informations sur l'appareil à l'aide du champ device.

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

Remplacer le code temporel

Le protocole de mesure utilise le premier code temporel qu'il trouve dans la liste suivante pour chaque événement et propriété utilisateur de la requête :

  1. Le timestamp_micros de l'événement ou de la propriété utilisateur.
  2. Le timestamp_micros de la demande.
  3. Heure à laquelle le protocole de mesure reçoit la requête.

L'exemple suivant envoie un code temporel au niveau de la requête qui s'applique à tous les événements et à toutes les propriétés utilisateur de la requête. Par conséquent, le protocole de mesure attribue un code temporel requestUnixEpochTimeInMicros aux événements tutorial_begin et join_group, ainsi qu'à la propriété utilisateur customer_tier.

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

L'exemple suivant envoie un code temporel au niveau de la requête, un code temporel au niveau de l'événement et un code temporel au niveau de la propriété utilisateur. Par conséquent, le protocole de mesure attribue les codes temporels suivants :

  • tutorialBeginUnixEpochTimeInMicros pour l'événement tutorial_begin
  • customerTierUnixEpochTimeInMicros pour la propriété utilisateur customer_tier
  • requestUnixEpochTimeInMicros pour l'événement join_group et la propriété utilisateur 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"
    }
  }
}

Comportement de validation pour les événements passés et les propriétés utilisateur

Les événements et les propriétés utilisateur peuvent être antidatés jusqu'à 72 heures. Si la valeur timestamp_micros est antérieure à 72 heures, le protocole de mesure accepte ou refuse l'événement ou la propriété utilisateur comme suit :

  • Si validation_behavior n'est pas défini ou est défini sur RELAXED, le protocole de mesure accepte l'événement ou la propriété utilisateur, mais remplace son code temporel par un code temporel datant de 72 heures.
  • Si validation_behavior est défini sur ENFORCE_RECOMMENDATIONS, le protocole de mesure rejette l'événement ou la propriété utilisateur.

Limites

Les limites suivantes s'appliquent à l'envoi d'événements du protocole de mesure à Google Analytics :

  • Les demandes ne doivent pas inclure plus de 25 événements.
  • Les événements ne doivent pas inclure plus de 25 paramètres.
  • Les événements ne doivent pas inclure plus de 25 propriétés utilisateur.
  • Les noms de propriétés utilisateur ne doivent pas dépasser 24 caractères.
  • Les valeurs des propriétés utilisateur ne doivent pas dépasser 36 caractères.
  • Les noms d'événements ne doivent pas dépasser 40 caractères. Ils ne doivent contenir que des caractères alphanumériques et des traits de soulignement, et doivent commencer par un caractère alphabétique.
  • Les noms de paramètres, y compris les paramètres d'article, ne doivent pas dépasser 40 caractères. Ils ne peuvent contenir que des caractères alphanumériques et des traits de soulignement, et doivent commencer par un caractère alphabétique.
  • Les valeurs de paramètres, y compris les valeurs des paramètres d'article, ne doivent pas dépasser 100 caractères pour une propriété Google Analytics standard et 500 caractères pour une propriété Google Analytics 360.
  • Les paramètres d'article peuvent comporter jusqu'à 10 paramètres personnalisés.
  • Le corps du post doit être inférieur à 130 Ko.
  • Le code temporel doit être compris dans les 72 dernières heures. Pour en savoir plus, consultez Comportement de validation pour les événements passés.
  • Les événements du protocole de mesure des applications envoyés à Google Analytics n'alimentent pas les audiences de recherche dans Google Ads pour les utilisateurs d'applications.

Pour connaître les exigences supplémentaires de chaque cas d'utilisation, consultez Cas d'utilisation courants.