Developers » Piano Analytics Tagging » Marquer des événements » API de collecte
API de collecte
Ce guide n'est disponible que pour des analyses sur Piano Analytics
Veuillez vérifier le tableau de compatibilité
Format
Objet d’event
Les événements suivent un modèle assez simple, nécessitant une propriété name
, valorisé par le nom de l’événement, et un objet de données data
, contenant toutes les propriétés de l’événement.
{ "name": "event.name", "data": { "property": "value", "property2": "value" } }
Requête GET
Format de la requête
Les événements peuvent être envoyés par des requêtes GET, dans le paramètre de requête events
. Ce paramètre prend un tableau d’objets d’événements.
https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&events=<events-array>&ref=<previous-url>
Avec les paramètres suivants :
Paramètre | Description | Exemple |
---|---|---|
collection-domain | Endpoint de collecte pour votre organisation | your.collection.domain |
path | Path de collect. Ne peut pas être vide | collect.path |
site-id | ID du site auquel les données doivent être rattachées | 123456 |
visitor-id | Identifiant unique du visiteur. GUID recommandé | 9e8d6d5f-143a-4a21-a7d5-7348b56e130d |
events-array | Tableau d’objets d’événements. URL encodé | %5B%7B%22name%22%3A%22event.name%22%2C%22data%22%3A%7B%22property%22%3A%22value%22%2C%22property2%22%3A%22value%22%7D%7D%5D |
previous-url | URL précédente encodée. Doit être le dernier paramètre de la querystring | https%3A%2F%2Fwww.piano.io |
Exemple
https://your.collection.domain/collect.path?s=123456789&idclient=9e8d6d5f-143a-4a21-a7d5-7348b56e130d&events=%5B%7B%22name%22%3A%22event.name%22%2C%22data%22%3A%7B%22property%22%3A%22value%22%2C%22property2%22%3A%22value%22%7D%7D%5D&ref=https%3A%2F%2Fwww.piano.io
Requête POST
Format de la requête
Endpoint
https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&ref=<previous-url>
Body
{ events: <event-array> }
Avec les paramètres suivants :
Paramètre | Description | Exemple |
---|---|---|
collection-domain | Endpoint de collecte pour votre organisation | your.collection.domain |
path | Path de collect. Ne peut pas être vide | collect.path |
site-id | ID du site auquel les données doivent être rattachées | 123456 |
visitor-id | Identifiant unique du visiteur. GUID recommandé | 9e8d6d5f-143a-4a21-a7d5-7348b56e130d |
events-array | Tableau d’objets d’événements |
|
previous-url | URL précédente encodée. Doit être le dernier paramètre de la querystring | https%3A%2F%2Fwww.piano.io |
Exemple
Endpoint
https://your.collection.domain/collect.path?s=123456789&idclient=9e8d6d5f-143a-4a21-a7d5-7348b56e130d&ref=https%3A%2F%2Fwww.piano.io
Body
{ events: [ { "name": "event.name", "data": { "property": "value", "property2": "value" } } ] }
Headers
Quelques en-têtes sont pris en compte, afin d’améliorer l’analyse.
Header | Description | Exemple |
---|---|---|
| User agent du client | User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0 |
Referer | Adresse de la page qui envoie les données | Referer: https://www.piano.io |
| Adresse IP du client | X-Forwarded-For: 129.78.138.66 |
Propriétés contextuelles communes
Quelques propriétés sont recommandées afin d’améliorer l’analyse.
Propriété | Description | Type | Exemple |
---|---|---|---|
event_collection_platform | Plateforme de collecte utilisé. Doit être api | string | "api" |
event_collection_version | Version de la plateforme de collecte utilisée. Doit être 2 | string | "2" |
| Timestamp du terminal (en secondes) | int | 1642685371 |
device_manufacturer | Fabricant de l’appareil | string | "Apple" |
| Modèle de l’appareil | string | "iPhone 13" |
device_display_height | Hauteur de la fenêtre d’affichage | int | 1057 |
device_display_width | Largeur de la fenêtre d’affichage | int | 1148 |
device_screen_height | Hauteur de l’écran du terminal | int | 1200 |
device_screen_width | Largeur de l’écran du terminal | int | 1920 |
Clés de propriété
La clé de propriété doit respecter ces règles :
- minuscule (notre traitement le mettra automatiquement en minuscule)
- caractères autorisés :
a→z
0→9
_
- pas d’espace
- commence par
a→z
- ne commence pas par :
m_
orvisit_
- ne peut pas être :
events
Type de propriété
Le type JSON est automatiquement attribué à la propriété.
Vous pouvez cependant forcer un type, en préfixant la clé de propriété par : s:
(string), n:
(integer), f:
(float), d:
(date), b:
(boolean), a:s:
(array of strings), a:n:
(array of integers), a:f:
(array of floats). Notre traitement essaiera ensuite alors de l’appliquer si la valeur est conforme.
Les propriétés se terminant par _date
, _utc
, _timestamp
et _ts
sont automatiquement traiter comme des dates si la valeur :
- est une date au format
YYYYMMDD
ouYYYY-MM-DD
- est un timestamp en secondes
- est conforme à la norme RFC 3339
YYYY-MM-DDTHH:mm:ssZ