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:
- Transport : vers et où envoyer les données
- Charge utile : les données que vous envoyez
Ce document explique comment mettre en forme les deux.
Transport
Point de terminaison d'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 des requêtes POST ou GET.
Utiliser POST
Nous vous recommandons d'envoyer les données via POST, car elles acceptent une charge utile plus importante. Lorsque vous utilisez la méthode POST, exécutez la requête HTTP suivante:
User-Agent: user_agent_string POST https://www.google-analytics.com/collect payload_data
Où :
- user_agent_string est une chaîne user-agent mise en forme qui permet de calculer les dimensions suivantes: navigateur, plate-forme et capacités mobiles.
Si cette valeur n'est pas définie, les données ci-dessus ne seront pas calculées.
- payload_data :
BODYde 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/de réseau dans Google Analytics.
CONSULTEZ
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. La longueur de l'URL encodée 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 suivantes 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. Toutes les requêtes du protocole de mesure sont ainsi uniques, et les requêtes ultérieures ne sont pas récupérées dans le 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 les données de la charge utile sont incorrectes, ou si les données de la charge utile sont incorrectes ou n'ont pas été traitées par Google Analytics.
Si vous n'obtenez pas de code d'état 2xx, vous ne devez PAS relancer la requête. Vous devez plutôt arrêter et corriger les erreurs dans votre requête HTTP.
Données utiles
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 est associé à une clé et à une valeur, est séparée par un caractère =, et chaque paire est séparée par un caractère &.
Exemple :
key1=val1&key2=val2
Chaque charge utile comporte des règles régissant les valeurs requises, l'encodage URI, les paramètres pouvant être envoyés ensemble et la longueur des paramètres. En outre, chaque paramètre est associé à un type spécifique nécessitant un format particulier. Les sections suivantes passent en revue ces règles.
Consultez la documentation de référence sur les paramètres pour obtenir la liste complète de tous les paramètres que vous pouvez envoyer via le protocole de mesure.
Valeurs obligatoires pour tous les appels
Les paramètres suivants doivent figurer dans chaque charge utile:
| Nom | Paramètre | 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 qui permet de distinguer la propriété Google Analytics à laquelle envoyer les données. |
| ID client | cid |
cid=xxxxx |
Identifiant unique attribué à un utilisateur particulier. |
| Type de l'appel | t |
t=pageview |
Type d'interaction collectée pour un utilisateur donné. |
Les données Client ID et Hit Type sont des valeurs mappées directement au modèle de données Google Analytics.
Si vous souhaitez suivre l'utilisateur 5555 ayant 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 %2F.
Valeurs d'encodage d'URL
Toutes les valeurs envoyées à Google Analytics doivent être au format UTF-8 et encodées en URL.
Pour envoyer la clé dp avec la valeur /my page €, vous devez d'abord vous assurer qu'il est encodé au format UTF-8, puis encodé au format URL, ce qui génère la chaîne finale:
dp=%2Fmy%20page%20%E2%82%AC
Si l'un des caractères n'est pas encodé correctement, il sera 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 pour chaque type d'appel.
Longueur maximale
Certaines valeurs textuelles du protocole de mesure ont une longueur maximale spécifique en octets. Par exemple, la longueur maximale du champ de l'URL de provenance du fichier dr est de 2 048 octets. Si l'une des valeurs est supérieure à la longueur maximale autorisée, elle sera automatiquement tronquée. Si un caractère codé sur plusieurs octets dépasse la longueur maximale, il sera tronqué.
Types de données acceptés
Chaque champ de données du protocole de mesure appartient à un type spécifique, chacun avec ses propres règles de validation. Si l'une des valeurs de paramètre n'est pas conforme aux règles de validation, le paramètre spécifique sera ignoré et ne sera pas traité par Google Analytics. Tous les autres paramètres seront traités normalement.
Le protocole de mesure accepte les types de données suivants:
Notez que des champs de données individuels peuvent avoir leurs propres restrictions. Consultez la documentation de référence sur les champs pour obtenir la liste complète de tous les champs de données et les types acceptés.
Texte
Utilisé pour représenter des chaînes. Un traitement supplémentaire est effectué dans les champs de texte. Tous les espaces blancs de début et de fin sont supprimés. Les exécutions internes d'au moins deux espaces blancs (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 qu'elle ne soit tronquée. Exemple :
Hello World
devient:
Hello World
Currency
Utilisé pour représenter la valeur totale d'une devise. Le point décimal est utilisé comme séparateur entre la partie entière et la fraction. La précision est de six décimales. Les informations 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). Exemple :
$-55.00
devient:
-55.00
Booléen
Permet de déterminer si une valeur est vraie ou fausse. Les valeurs possibles sont les suivantes :
1– Vrai0– Faux
Integer
Utilisé pour représenter un entier. La valeur est stockée en tant que valeur int64 signée
Number
Utilisé pour représenter un nombre entier ou un nombre à virgule flottante.