Documentation de référence du protocole de mesure

Ce document explique comment envoyer des données à Google Analytics à l'aide du protocole de mesure.

Présentation

Pour envoyer des données à Google Analytics à l'aide du protocole de mesure, vous devez suivre deux étapes:

  • Le transport : où et comment vous envoyez des données
  • La charge utile : les données que vous envoyez

Ce document explique comment mettre en forme ces deux éléments.

Transport

Point de terminaison de l'URL

Pour envoyer des données à l'aide du protocole de mesure, envoyez des requêtes HTTP au point de terminaison suivant:

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

Toutes les données doivent être envoyées de manière sécurisée via le protocole HTTPS.

Vous pouvez envoyer des données à l'aide de requêtes POST ou GET.

Utiliser la méthode POST

Nous vous recommandons d'envoyer des données via POST, car cela permet une charge utile plus importante. Lorsque vous utilisez POST, envoyez la requête HTTP suivante:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Où :

  • user_agent_string : correspond à une chaîne user-agent mise en forme qui permet de calculer les dimensions suivantes : fonctionnalités du navigateur, de la plate-forme et du mobile.

    Si cette valeur n'est pas définie, les données ci-dessus ne seront pas calculées.

  • payload_data : BODY de la requête post. Le corps doit inclure exactement une charge utile encodée en URI et ne doit pas dépasser 8 192 octets.
  • Adresse IP : est envoyée implicitement dans la requête HTTP et permet de calculer toutes les dimensions géographiques / réseau dans Google Analytics.

GET

Pour les environnements dans lesquels vous ne pouvez pas envoyer de données POST, vous pouvez également envoyer des requêtes HTTP GET au même point de terminaison:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Où les données de charge utile sont envoyées en tant que paramètres de requête avec échappement de l'URI. La longueur de l'URL encodée complète ne doit pas dépasser 8 000 octets.

Contournement du cache

Dans certains environnements, tels que les navigateurs, les requêtes HTTP GET peuvent être mises en cache. Lorsqu'une requête est mise en cache, les requêtes ultérieures peuvent être extraites du cache et ne pas être envoyées à Google Analytics. Pour contourner le cache, le protocole de mesure fournit un paramètre spécial (z) qui peut être défini avec un nombre aléatoire. Cela garantit que toutes les requêtes du protocole de mesure sont uniques et que les requêtes ultérieures ne sont pas extraites du cache.

Lorsque vous utilisez le cache buster, nous vous recommandons vivement d'ajouter ce paramètre en tant que dernier paramètre de la charge utile.

https://www.google-analytics.com/collect?payload_data&z=123456

Codes de réponse

Le protocole de mesure renvoie un code d'état 2xx si la requête HTTP a été reçue. Le protocole de mesure ne renvoie pas de code d'erreur si le format des données de la charge utile est incorrect, si les données de la charge utile étaient incorrectes ou si elles n'ont pas été traitées par Google Analytics.

Si vous ne recevez pas de code d'état 2xx, vous ne devez PAS relancer la requête. À la place, vous devez arrêter et corriger les erreurs dans votre requête HTTP.

Données de charge utile

Toutes les données collectées par Google Analytics à l'aide du protocole de mesure sont envoyées en tant que charge utile. La charge utile ressemble à une chaîne de requête d'URL dans laquelle chaque paramètre a une clé et une valeur, est séparé par un caractère =, et chaque paire est délimitée par un caractère &. Exemple :

key1=val1&key2=val2

Chaque charge utile est associée à des règles régissant les valeurs requises, l'encodage de l'URI, les paramètres pouvant être envoyés ensemble et la longueur des paramètres. De plus, chaque paramètre possède un type spécifique nécessitant un format particulier. Les sections suivantes décrivent ces règles.

Consultez la documentation de référence pour obtenir la liste complète des paramètres que vous pouvez envoyer à l'aide du protocole de mesure.

Valeurs requises pour tous les appels

Les paramètres suivants doivent figurer dans chaque charge utile:

Nom Paramètres Exemple Description
Version du protocole v v=1 Version du protocole. La valeur doit être 1.
ID de suivi tid tid=UA-123456-1 ID permettant de distinguer la propriété Google Analytics à laquelle les données doivent être envoyées.
ID client cid cid=xxxxx Identifiant propre à un utilisateur particulier.
Type de l'appel t t=pageview Type d'interaction collecté pour un utilisateur particulier.

Les données Client ID et Hit Type sont des valeurs directement mappées avec le modèle de données Google Analytics. Si vous souhaitez suivre l'utilisateur 5555 qui a accédé à /pageA, /pageB et /pageC, vous devez envoyer les trois charges utiles suivantes:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Notez que / a été encodé sous la forme %2F.

Valeurs d'encodage d'URL

Toutes les valeurs envoyées à Google Analytics doivent être à la fois en UTF-8 et encodées au format URL. Pour envoyer la clé dp avec la valeur /my page €, vous devez d'abord vous assurer qu'elle est encodée en UTF-8, puis en URL, ce qui donne la chaîne finale:

dp=%2Fmy%20page%20%E2%82%AC

Si l'un des caractères n'est pas encodé correctement, il est remplacé par le caractère de remplacement Unicode xFFFD.

Valeurs requises pour certains types d'appels

Certains paramètres ne peuvent être envoyés qu'avec des types d'appels spécifiques. Par exemple, le type d'appel pageview nécessite que le paramètre "Chemin de la page" (dp) soit également défini. La documentation de référence sur les paramètres décrit les paramètres requis en fonction des types d'appels.

Longueur maximale

Certaines valeurs textuelles du protocole de mesure ont des longueurs maximales spécifiques en octets. Par exemple, le champ de provenance du document dr a une longueur maximale de 2 048 octets. Si l'une des valeurs est supérieure aux longueurs maximales, elle sera automatiquement tronquée. Si un caractère multi-octet dépasse la longueur maximale, le caractère entier est tronqué.

Types de données acceptés

Chaque champ de données du protocole de mesure appartient à un type spécifique, ayant chacun ses propres règles de validation. Si l'une des valeurs de paramètre n'est pas conforme aux règles de validation, ce paramètre spécifique sera ignoré et ne sera pas traité par Google Analytics. Tous les autres paramètres sont traités normalement.

Le protocole de mesure accepte les types de données suivants:

Notez que les champs de données individuels peuvent être soumis à leurs propres restrictions. Consultez la documentation de référence sur les champs pour obtenir la liste complète des champs de données et des types acceptés.

Texte

Utilisé pour représenter des chaînes. Un traitement supplémentaire est effectué sur les champs de texte. Tous les espaces blancs de début et de fin sont supprimés. Les exécutions internes de deux caractères d'espace blanc ou plus (y compris l'espace, la tabulation, les sauts de ligne, etc.) sont réduites à un seul caractère d'espacement. Cette transformation est appliquée au texte brut avant toute troncation. Exemple :

   Hello      World

deviendra:

Hello World

Devise

Utilisé pour représenter la valeur totale d'une devise. Le séparateur décimal est utilisé comme séparateur décimal. La précision est de six décimales. Les valeurs suivantes sont valides pour un champ de devise:

1000.000001

Une fois la valeur envoyée à Google Analytics, tout le texte est supprimé jusqu'au premier chiffre, au caractère - ou au caractère . (décimal). Comme suit :

$-55.00

deviendra:

-55.00

Booléen

Permet de déterminer si une valeur est vraie ou fausse. Les valeurs possibles sont les suivantes :

  • 1 – Vrai
  • 0 – Faux

Entier

Permet de représenter un nombre entier. La valeur est stockée sous la forme d'un int64 signé

Nombre

Permet de représenter un nombre entier ou à virgule flottante.