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, 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 : Vrai
  • 0 : 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.