Essayez le serveur MCP pour Google Analytics. Installez-le depuis GitHub et consultez l'annonce pour en savoir plus.

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.

Sélectionnez la plate-forme que vous souhaitez afficher dans ce guide :

Mise en forme de la requête

Le protocole de mesure Google Analytics n'est compatible qu'avec 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 du protocole de mesure > Créer.

firebase_app_id: ID de l'application Firebase, que vous trouverez dans la console Firebase sous Paramètres du projet > Général > Vos applications > ID de l'application.

firebase_app_id n'est pas identique à app_instance_id. firebase_app_id identifie votre application, tandis que app_instance_id identifie une seule installation de l'application.

Vous devez fournir un corps de requête au format 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
        }
      }
   ]
  }

Même si session_start est un nom d'événement réservé, créer un nouveau 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 tutorial_begin événement et un join_group événement à votre serveur Google Analytics, inclut des informations géographiques à l'aide du champ user_location et 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 l'horodatage

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

Le timestamp_micros de l'événement ou de la propriété utilisateur.
Le timestamp_micros de la requête.
L'heure à laquelle le protocole de mesure reçoit la requête.

L'exemple suivant envoie un horodatage au niveau de la requête qui s'applique à tous les événements et propriétés utilisateur de la requête. Par conséquent, le protocole de mesure attribue un horodatage 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 horodatage au niveau de la requête, un horodatage au niveau de l'événement et un horodatage au niveau de la propriété utilisateur. Par conséquent, le protocole de mesure attribue les horodatages 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 rétrodaté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 horodatage par celui d'il y a 72 heures.
Si validation_behavior est défini sur ENFORCE_RECOMMENDATIONS, le protocole de mesure refuse l'événement ou la propriété utilisateur.

Les événements envoyés à l'aide du protocole de mesure et destinés à être associés ou traités conjointement avec des é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 l'horodatage d'origine de l'événement côté client. Les événements reçus après ce délai peuvent ne pas être traités comme prévu, en particulier à des fins telles que l'attribution des conversions.

Limites

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

Les requêtes ne peuvent pas comporter 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 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 ne peuvent pas comporter plus de 10 paramètres personnalisés.
Le corps de la requête POST doit être inférieur à 130 Ko.
Les événements du protocole de mesure d'application envoyés à Google Analytics ne remplissent pas les audiences de recherche dans Google Ads pour les utilisateurs d'applications.
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 pour détails.

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 ni les propriétés utilisateur.

Les noms d'événements suivants sont souvent source de confusion :

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

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