Collection API

Data collection / Piano Analytics / Event tagging piano analytics / 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:

Parameter	Description	Example
collection-domain	Collection endpoint for your organisation	your.collection.domain
path	Collection path. Can’t be empty	collect.path
site-id	ID of the site the data belongs to	123456
visitor-id	Unique identifier of the visitor. GUID recommended	9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-array	Array 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-url	Encoded previous URL. Must be the latest querystring parameter	https%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:

Parameter	Description	Example
collection-domain	Collection endpoint for your organisation	your.collection.domain
path	Collection path. Can’t be empty	collect.path
site-id	ID of the site the data belongs to	123456
visitor-id	Unique identifier of the visitor. GUID recommended	9e8d6d5f-143a-4a21-a7d5-7348b56e130d
events-array	Array of events objects	[{"name": "event.name", "data": { "property": "value", "property2": "value" }}]
previous-url	Encoded previous URL. Must be the latest querystring parameter	https%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.

Header	Description	Example
User-Agent	User agent of the client	User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0
Referer	Address of the page sending the data	Referer: https://www.piano.io
X-Forwarded-For	IP address of the client	X-Forwarded-For: 129.78.138.66

Common contextual properties

A few properties are recommended in order to enhance analysis.

Property	Description	Type	Example
event_collection_platform	Collection platform used. Must be api	string	"api"
event_collection_version	Version of the collection platform. Must be 2	string	"2"
device_timestamp_utc	Timestamp of the device (in seconds)	int	1642685371
device_manufacturer	Manufacturer of the device	string	"Apple"
device_model	Model of the device	string	"iPhone 13"
device_display_height	Height of the viewport	int	1057
device_display_width	Width of the viewport	int	1148
device_screen_height	Height of the device screen	int	1200
device_screen_width	Width of the device screen	int	1920

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