Developers » Piano Analytics tagging » Event tagging » Collection API
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 |
|
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 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 |
| 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" |
| Timestamp of the device (in seconds) | int | 1642685371 |
device_manufacturer | Manufacturer of the device | string | "Apple" |
| 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_
orvisit_
- 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
orYYYY-MM-DD
- is Timestamp in seconds
- complies with the RFC 3339 standard
YYYY-MM-DDTHH:mm:ssZ