Documentation de référence sur le protocole de mesure

Cette page décrit le mécanisme de transport et les paramètres de données du protocole de mesure.

Transport

Toutes les données doivent être envoyées de manière sécurisée à l'aide de requêtes HTTPS POST.

Envoyez des requêtes au point de terminaison suivant :

https://www.google-analytics.com/mp/collect

Si vous souhaitez que vos données soient traitées dans l'UE, utilisez plutôt le point de terminaison suivant :

https://region1.google-analytics.com/mp/collect

Voici un exemple de requête POST :

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

Remplacez PAYLOAD_DATA par Payload de la requête.

Le protocole de mesure renvoie un code d'état 2xx si la requête HTTP est reçue. Le protocole de mesure ne renvoie pas de code d'erreur si la charge utile est mal formée, ou si les données sont incorrectes ou ne sont pas traitées par Google Analytics.

Charge utile

La charge utile se compose de deux parties :

  1. Paramètres de requête.
  2. Corps JSON POST.

Paramètres de requête

Nom du paramètre Description

api_secret

 Obligatoire. Le code secret de l'API de l'UI Google Analytics.

Vous le trouverez sous Administration > Flux de données > Choisissez votre flux  > Protocole de mesure > Créer.

Privée pour votre organisation. Doit être mis à jour régulièrement pour éviter le spam excessif.

Corps POST JSON

Clé Type Description

user_id

 string

Facultatif. identifiant unique d'un utilisateur. Pour en savoir plus sur cet identifiant, consultez User-ID pour l'analyse multiplate-forme. Ne peut contenir que des caractères UTF-8.

timestamp_micros

 number

Facultatif. Code temporel Unix en microsecondes, et non en millisecondes. Représente l'heure de l'événement. Doit être défini uniquement pour enregistrer les événements passés. Peut être remplacé par user_property ou des codes temporels d'événement. Les événements peuvent être antidatés jusqu'à trois jours calendaires en fonction du fuseau horaire de la propriété.

user_properties

 object Facultatif. Les propriétés utilisateur pour la mesure.

user_data

 object Facultatif. Données fournies par l'utilisateur.
object Facultatif. Paramètres de consentement pour la demande. Pour en savoir plus, consultez la section Consentement.

non_personalized_ads

 boolean Facultatif. Définissez la valeur sur true pour indiquer que les données de l'utilisateur ne doivent pas être utilisées pour les annonces personnalisées.

user_location

 object Facultatif. Définit les informations géographiques de la requête dans un format structuré.

ip_override

 string Facultatif. Adresse IP utilisée par Google Analytics pour obtenir des informations géographiques pour la requête.

device

 object Facultatif. Définit les informations sur l'appareil pour la requête dans un format structuré.

events[]

 array Obligatoire. Tableau d'éléments event. Vous pouvez envoyer jusqu'à 25 événements par requête. Consultez la documentation de référence sur les événements pour connaître tous les événements valides.

events[].name

 string Obligatoire. Nom de l'événement. Consultez Événements pour découvrir toutes les options.

events[].params

 object Facultatif. Paramètres de l'événement. Consultez Événements pour connaître les paramètres suggérés pour chaque événement et Paramètres d'événement courants.

Paramètres d'événement courants

Le protocole de mesure comporte les paramètres d'événement courants suivants :

Clé Type Description

session_id

 number Nombre positif qui identifie la session utilisateur. Nécessaire pour plusieurs cas d'utilisation courants. Doit correspondre à l'expression régulière ^\d+$.

engagement_time_msec

 number Durée de l'engagement utilisateur, en millisecondes, pour l'événement. Utilisez une valeur qui reflète la durée d'engagement de l'utilisateur depuis l'événement précédent.

timestamp_micros

 number epoch Unix (en microsecondes) de l'événement. Utilisez ce paramètre pour remplacer l'horodatage de l'événement.

L'attribut consent configure les types et les états de consentement. Si vous ne spécifiez pas consent, Google Analytics utilise les paramètres de consentement des interactions en ligne correspondantes pour l'instance client ou d'application.

Clé Type Description

ad_user_data

 string

Facultatif. Consentement pour l'envoi à Google des données utilisateur provenant des événements et des propriétés utilisateur de la demande à des fins publicitaires.

GRANTED ou DENIED.

ad_personalization

 string

Facultatif. Consentement de l'utilisateur pour la publicité personnalisée.

GRANTED ou DENIED.

Informations géographiques

Les attributs user_location et ip_override fournissent des informations géographiques. user_location est prioritaire sur ip_override.

Voici la structure du champ user_location. Fournissez autant d'attributs que possible. Nous vous recommandons d'utiliser au moins country_id et region_id.

Clé Type Description

city

 string Facultatif. Le nom de la ville. Si la ville se trouve aux États-Unis, définissez également country_id et region_id afin que Google Analytics puisse mapper correctement le nom de la ville à un ID de ville.

region_id

 string Facultatif. Pays et subdivision ISO 3166. Par exemple, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Facultatif. Pays au format ISO 3166-1 alpha-2. Par exemple, US, AU, ES, FR.

subcontinent_id

 string Facultatif. Sous-continent au format UN M49. Par exemple, 011, 021, 030, 039.

continent_id

 string Facultatif. Continent au format UN M49. Par exemple, 002, 019, 142, 150.

Voici un exemple de user_location :

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override est une alternative à user_location. Si vous envoyez ip_override, Google Analytics déduit les informations géographiques de l'adresse IP. Si vous envoyez user_location, Google Analytics ignore ip_override.

Si vous n'envoyez pas user_location ni ip_override, Google Analytics déduit les informations géographiques des événements de taggage à l'aide de client_id.

Google Analytics applique les paramètres de données de localisation précises de la propriété à la requête, quelles que soient les informations géographiques envoyées.

Informations sur l'appareil

Pour envoyer des informations sur l'appareil, utilisez le champ device. Voici la structure du champ device. Fournissez autant d'attributs que possible. Nous vous recommandons de définir au moins category.

Clé Type Description

category

 string Facultatif. Catégorie de l'appareil. Par exemple, desktop, tablet, mobile, smart TV.

language

 string Facultatif. Langue au format ISO 639-1. Par exemple, en, en-US.

screen_resolution

 string Facultatif. Résolution de l'appareil, au format WIDTHxHEIGHT. Par exemple, 1280x2856, 1080x2340.

operating_system

 string Facultatif. Système d'exploitation ou plate-forme. Par exemple, MacOS.

operating_system_version

 string Facultatif. Version du système d'exploitation ou de la plate-forme. Par exemple, 13.5.

model

 string Facultatif. Modèle de l'appareil. Par exemple, Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Facultatif. Marque de l'appareil. Par exemple, Google, Samsung.

browser

 string Facultatif. Marque ou type de navigateur. Par exemple, Chrome, Firefox.

browser_version

 string Facultatif. Version du navigateur. Par exemple, 136.0.7103.60, 5.0.

L'extrait suivant montre un exemple de paramètres device :

"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"
}

Que vous spécifiiez Google Analytics applique les paramètres de données détaillées sur les appareils de la propriété à la requête.

Paramètres personnalisés

Vous pouvez inclure des paramètres personnalisés de portée utilisateur, événement et article dans une charge utile du Measurement Protocol.

  • Des paramètres personnalisés de portée utilisateur peuvent être inclus dans user_properties.
  • Des paramètres personnalisés de portée événement peuvent être inclus dans events[].params.
  • Des paramètres personnalisés de portée article peuvent être inclus dans items.

Certains événements ont des paramètres recommandés. Consultez Événements pour connaître les paramètres recommandés pour tous les événements acceptés.

Noms réservés

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 :

Noms d'événements réservés

Les noms d'événements suivants sont réservés et ne peuvent pas être utilisés :

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Noms de paramètres réservés

Les noms de paramètres suivants sont réservés et ne peuvent pas être utilisés :

  • firebase_conversion

Les noms de paramètres ne peuvent pas commencer par :

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Noms de propriétés utilisateur réservés

Les noms de propriétés utilisateur suivants sont réservés et ne peuvent pas être utilisés :

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

De plus, les noms de propriétés utilisateur ne peuvent pas commencer par :

  • _ (underscore)
  • firebase_
  • ga_
  • google_