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ètreDescriptionExemple
collection-domainEndpoint de collecte pour votre organisationyour.collection.domain
pathPath de collect. Ne peut pas être videcollect.path
site-idID du site auquel les données doivent être rattachées123456
visitor-idIdentifiant unique du visiteur. GUID recommandé9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-arrayTableau 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-urlURL précédente encodée. Doit être le dernier paramètre de la querystringhttps%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ètreDescriptionExemple
collection-domainEndpoint de collecte pour votre organisationyour.collection.domain
pathPath de collect. Ne peut pas être videcollect.path
site-idID du site auquel les données doivent être rattachées123456
visitor-idIdentifiant unique du visiteur. GUID recommandé9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-arrayTableau d’objets d’événements[{"name": "event.name", "data": { "property": "value", "property2": "value" }}]
previous-urlURL précédente encodée. Doit être le dernier paramètre de la querystringhttps%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.

HeaderDescriptionExemple
User-AgentUser agent du clientUser-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0
RefererAdresse de la page qui envoie les donnéesReferer: https://www.piano.io
X-Forwarded-ForAdresse IP du clientX-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éDescriptionTypeExemple
event_collection_platformPlateforme de collecte utilisé. Doit être apistring"api"
event_collection_versionVersion de la plateforme de collecte utilisée. Doit être 2string"2"
device_timestamp_utcTimestamp du terminal (en secondes)int1642685371
device_manufacturerFabricant de l’appareilstring"Apple"
device_modelModèle de l’appareilstring"iPhone 13"
device_display_heightHauteur de la fenêtre d’affichageint1057
device_display_widthLargeur de la fenêtre d’affichageint1148
device_screen_heightHauteur de l’écran du terminalint1200
device_screen_widthLargeur de l’écran du terminalint1920
 

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_ or visit_
  • 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 ou YYYY-MM-DD
  • est un timestamp en secondes
  • est conforme à la norme RFC 3339 YYYY-MM-DDTHH:mm:ssZ
Dernière mise à jour : 05/07/2022