Piano Analytics Tagging » Marquer des événements » API de collecte

API de collecte

Format
Objet d’event
Requête GET
Format de la requête
Exemple
Requête POST
Format de la requête
Exemple
Headers
Propriétés contextuelles communes
Clés de propriété
Type de propriété

Ce guide n'est disponible que pour des analyses sur Piano Analytics
Si vos périmètres sont certifiés (ACPM / Mediamétrie), merci de ne pas utiliser le Piano Analytics Tagging
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	`[{"name": "event.name", "data": { "property": "value", "property2": "value" }}]`
`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`	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`
`X-Forwarded-For`	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"`
`device_timestamp_utc`	Timestamp du terminal (en secondes)	int	`1642685371`
`device_manufacturer`	Fabricant de l’appareil	string	`"Apple"`
`device_model`	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_ 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

Developers » Piano Analytics Tagging » Marquer des événements » API de collecte