Collection API

This guide is only available for Piano Analytics analysis

Please check the compatibility table

 

Pattern

 

Event object

Events are following a rather simple pattern, requiring a name, valued with the event name, and a data object, containing all the properties for the event.

{
  "name": "event.name",
  "data": {
    "property": "value",
    "property2": "value"
  }
}
 

GET request

 

Request pattern

Events can be sent through GET requests, in the query parameter events. This parameter takes an array of event objects.

https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&events=<events-array>&ref=<previous-url>

With the following parameters:

ParameterDescriptionExample
collection-domainCollection endpoint for your organisationyour.collection.domain
pathCollection path. Can’t be emptycollect.path
site-idID of the site the data belongs to123456
visitor-idUnique identifier of the visitor. GUID recommended9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-arrayArray of events objects. URL encoded%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-urlEncoded previous URL. Must be the latest querystring parameterhttps%3A%2F%2Fwww.piano.io
 

Example

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
 

POST request

 

Request pattern

Endpoint

https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&ref=<previous-url>

Body

{
  events: <event-array>
}

With the following parameters:

ParameterDescriptionExample
collection-domainCollection endpoint for your organisationyour.collection.domain
pathCollection path. Can’t be emptycollect.path
site-idID of the site the data belongs to123456
visitor-idUnique identifier of the visitor. GUID recommended9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-arrayArray of events objects[{"name": "event.name", "data": { "property": "value", "property2": "value" }}]
previous-urlEncoded previous URL. Must be the latest querystring parameterhttps%3A%2F%2Fwww.piano.io
 

Example

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

A few headers are taken into account, in order to enhance analysis.

HeaderDescriptionExample
User-AgentUser agent of the clientUser-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0
RefererAddress of the page sending the dataReferer: https://www.piano.io
X-Forwarded-ForIP address of the clientX-Forwarded-For: 129.78.138.66
 

Common contextual properties

A few properties are recommended in order to enhance analysis.

PropertyDescriptionTypeExample
event_collection_platformCollection platform used. Must be apistring"api"
event_collection_versionVersion of the collection platform. Must be 2string"2"
device_timestamp_utcTimestamp of the device (in seconds)int1642685371
device_manufacturerManufacturer of the devicestring"Apple"
device_modelModel of the devicestring"iPhone 13"
device_display_heightHeight of the viewportint1057
device_display_widthWidth of the viewportint1148
device_screen_heightHeight of the device screenint1200
device_screen_widthWidth of the device screenint1920
 

Property keys

Property key must follow these rules:

  • lowercase (our processing will automatically lowercase it)
  • authorized characters: a→z 0→9 _
  • no space
  • begin with a→z
  • can’t begin with: m_ or visit_
  • can’t be: events
 

Property type

The JSON type is automatically assigned to the property.

You can however force a type, by prefixing the property key with: 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). Our processing will then try to cast it if the value complies.

Properties ending with _date, _utc, _timestamp and _ts are automatically casted as dates if the value:

  • is a date following this pattern: YYYYMMDD or YYYY-MM-DD
  • is Timestamp in seconds
  • complies with the RFC 3339 standard YYYY-MM-DDTHH:mm:ssZ
Last update: 05/07/2022