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, deux étapes sont nécessaires:
- Le transport : vers où et comment vous envoyez des données
- Charge utile : les données que vous envoyez
Ce document explique comment mettre en forme les deux.
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 à l'aide du protocole HTTPS.
Vous pouvez envoyer des données à l'aide de requêtes POST ou GET.
En utilisant la méthode POST
Nous vous recommandons d'envoyer les 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 :
chaîne user-agent mise en forme permettant de calculer les dimensions suivantes : navigateur, plate-forme et fonctionnalités mobiles.
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 dans 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 sont pas 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 suivantes 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 les données de la charge utile sont incorrectes, si elles sont 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. Vous devez plutôt arrêter et corriger toutes les erreurs contenues 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 est associé à une clé et à une valeur. Les deux éléments sont séparés 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 qui régissent les valeurs requises, l'encodage de l'URI, les paramètres pouvant être envoyés ensemble et leur longueur. 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 des paramètres 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 d'identifier la propriété Google Analytics à laquelle envoyer les données. |
ID client | cid |
cid=xxxxx |
Un identifiant propre à un utilisateur particulier. |
Type de l'appel | t |
t=pageview |
Type d'interaction collecté pour un utilisateur spécifique. |
Les données Client ID
et Hit Type
sont des valeurs directement mappées au 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é en %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. La chaîne finale est alors générée:
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
Il est possible que certains paramètres ne soient envoyés qu'avec des types d'appel 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 des 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, la longueur maximale du champ de provenance du document dr
est 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, l'intégralité du caractère sera tronqué.
Types de données acceptés
Chaque champ de données du protocole de mesure appartient à un type spécifique, chacun possédant ses propres règles de validation. Si l'une de ses valeurs ne respecte pas les règles de validation, le 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 comporter 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
Currency
Utilisé pour représenter la valeur totale d'une devise. Le point décimal sert de délimiteur entre l'ensemble et la fraction de la devise. 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, le caractère -
ou le caractère .
(décimal). Exemple :
$-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
: Vrai0
: Faux
Entier
Utilisé pour 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 un nombre à virgule flottante.