Le protocole de mesure est un produit mature et finalisé. Il restera opérationnel et ne sera pas abandonné. Toutefois, pour que vos configurations techniques soient pérennes, nous vous recommandons de créer des intégrations d'événements de serveur à serveur à l'aide de l'API Data Manager, qui constitue notre infrastructure centrale pour les futures innovations en matière d'ingestion de données.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 afin de pouvoir les consulter dans vos rapports Google Analytics.

Les identifiants et paramètres requis pour les requêtes du protocole de mesure dépendent de l'envoi d'événements à un flux Web ou à un flux d'application.

Pour les flux Web (généralement instrumentés avec gtag.js ou Google Tag Manager), vous utilisez measurement_id dans l'URL de la requête et client_id dans le corps JSON pour identifier l'instance utilisateur. L'client_id doit correspondre à l'ID généré par la balise Google Analytics sur votre site Web.
Pour les flux d'application (instrumentés avec le SDK Firebase), vous utilisez le firebase_app_id dans l'URL de la requête et le app_instance_id dans le corps JSON, qui sont fournis par le SDK Google Analytics pour Firebase.

Ce guide fournit des exemples pour les deux scénarios.

Composants clés de la requête par type de flux

Composant	Flux Web (gtag.js/GTM)	Flux d'application (Firebase)
Paramètre d'URL du flux de données	`measurement_id`	`firebase_app_id`
Paramètre d'URL du code secret de l'API	Obligatoire	Obligatoire
Champ de corps JSON de l'ID de l'appareil	`client_id`	`app_instance_id`

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

Cet onglet indique comment envoyer des événements depuis votre serveur qui correspondent à l'activité des utilisateurs dans un flux d'application à l'aide du SDK Google Analytics for Firebase. N'oubliez pas que ces requêtes utilisent firebase_app_id et app_instance_id.

Prérequis

Pour envoyer des événements à l'aide du protocole de mesure, vous avez besoin d'identifiants spécifiques de votre propriété Google Analytics ou de votre projet Firebase.

Code secret de l'API

Le api_secret permet d'authentifier vos requêtes. Il est essentiel de garder ce secret confidentiel.

Pour créer un secret:

Accédez à Google Analytics, puis à votre compte et à votre propriété.
Cliquez sur Admin en bas à gauche.
Sous Collecte et modification des données, cliquez sur Flux de données.
Sélectionnez votre flux de données Web ou d'application.
Cliquez sur Codes secrets de l'API du protocole de mesure.
Cliquez sur Créer.
Saisissez un pseudo pour le secret, puis cliquez sur Créer.
Copiez la valeur du secret.
Important : Le api_secret est privé. Ne l'exposez pas dans le code côté client de votre site Web ou de votre application.
- Risque de sécurité : l'exposition de api_secret permet à des tiers non autorisés d'envoyer des données arbitraires ou du spam à votre propriété Google Analytics, ce qui peut corrompre vos rapports.
- Utilisation correcte : le protocole de mesure est principalement conçu pour les environnements côté serveur ou de confiance (comme les systèmes hors connexion ou la communication de serveur à serveur).
- Suivi côté client : si vous devez envoyer des événements directement depuis un navigateur Web, utilisez la balise Google (gtag.js) ou Google Tag Manager.
- Extensions Chrome : pour les extensions Chrome Manifest V3, vous ne pouvez pas charger de code distant tel que gtag.js. Dans ce cas, le protocole de mesure est l'approche recommandée. Consultez Utiliser Google Analytics dans les extensions Chrome.

ID de l'application Firebase

firebase_app_id identifie votre application Firebase. Il est différent de app_instance_id.

Pour trouver l'ID de votre application Firebase :

Ouvrez votre projet dans la console Firebase.
Cliquez sur l'icône en forme de roue dentée à côté de Aperçu du projet, puis sélectionnez Paramètres du projet.
Dans l'onglet Général, accédez à la section Vos applications.
Sélectionnez l'application iOS ou Android spécifique.
Copiez la valeur ID de l'application.

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?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

Vous devez fournir les éléments suivants dans les paramètres de requête de l'URL de la requête (pour savoir comment trouver ou créer ces valeurs, consultez la section Prérequis) :

api_secret : code secret de l'API pour authentifier la requête.
firebase_app_id : ID de votre application Firebase.

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

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

Vous devez fournir app_instance_id dans le corps de la requête pour identifier une installation unique de votre application mobile. Notez que ce paramètre est différent de firebase_app_id, qui identifie l'application elle-même. Pour en savoir plus sur l'app_instance_id et sur la façon de le récupérer à l'aide du SDK Firebase, consultez la documentation de référence sur app_instance_id.

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, inclut des informations géographiques à l'aide du champ user_location et inclut des informations sur l'appareil à l'aide du champ 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"
    }
  })
});

Le format de firebase_app_id est spécifique à la plate-forme. Consultez ID d'application sous Fichiers et objets de configuration Firebase.

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 :

timestamp_micros de l'événement ou de la propriété utilisateur.
timestamp_micros de la requête.
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 de 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 et propriétés utilisateur passés

Les événements et les propriétés utilisateur peuvent être antidatés de 72 heures maximum. 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 une valeur 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.

Les événements envoyés à l'aide du protocole de mesure qui sont destinés à être associés ou traités conjointement avec les événements collectés par le SDK Google Analytics for Firebase ou gtag.js doivent être reçus par Google Analytics dans les 48 heures suivant le code temporel de l'événement côté client d'origine. Les événements reçus après ce délai risquent de ne pas être traités comme prévu, en particulier pour l'attribution des conversions.

Limites

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

Vous pouvez envoyer au maximum 100 millions de requêtes sans conversion par heure pour chaque propriété. Une requête est considérée comme une requête sans conversion si aucun des événements qu'elle contient n'est un événement clé pour lequel il existe une conversion dans Google Ads. Si vous dépassez cette limite, Measurement Protocol ignore silencieusement toutes les requêtes de non-conversion pour la propriété pendant le reste de l'heure.

Important : Cette limite ne s'applique pas aux propriétés Google Analytics 360.
Les requêtes peuvent comporter 25 événements au maximum.
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 doivent 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.

Cette limite ne s'applique pas aux paramètres session_id et session_number lorsque leurs valeurs sont fournies par les variables intégrées ID de session Analytics et Numéro de session Analytics correspondantes dans Google Tag Manager.
Les paramètres d'article peuvent comporter jusqu'à 10 paramètres personnalisés.
Le corps du post doit faire moins de 130 Ko.
Les événements du protocole de mesure d'application envoyés à Google Analytics ne remplissent pas les audiences sur le Réseau de Recherche dans Google Ads pour les utilisateurs de l'application.
Certains noms d'événements, de paramètres et de propriétés utilisateur sont réservés et ne peuvent pas être utilisés. Pour en savoir plus, consultez Noms réservés.

Noms réservés

Le protocole de mesure comporte plusieurs noms réservés qui ne peuvent pas être utilisés pour les événements, les paramètres ou les propriétés utilisateur.

Les noms d'événements suivants sont souvent confondus :

screen_view : cet événement n'est autorisé que pour les flux d'applications. Pour les flux Web, utilisez plutôt page_view.
ad_impression : cet événement n'est autorisé que pour les flux d'applications.
in_app_purchase : cet événement n'est autorisé que pour les flux d'applications. Pour les flux Web, utilisez plutôt l'événement purchase.

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