Collection API
If you're not yet confortable with the "Collection API" notion, don't hesitate to consult the Implementation methods article.
You will find here all information you need to send events directly to our Collection API, from any platform you want!
Pattern
Event object
{
"name": "event.name",
"data": {
"property": "value",
"property2": "value"
}
}
GET
Pattern
https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&events=<events-array>
Variable | Description | Example |
---|---|---|
collection-domain | Collection endpoint for your organisation | your.collection.domain |
path | Collection path | event |
site-id | ID of the site the data belongs | 123456789 |
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 |
note
Don't hesitate to read our collection methods article to find the collection domain that has been assigned to you.
You can also use a custom domain thanks to our CDDC.
Example
https://your.collection.domain/event?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
POST
Endpoint:
https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>
Body:
{
events: <event-array>
}
Variable | Description | Example |
---|---|---|
collection-domain | Collection endpoint for your organisation | your.collection.domain |
path | Collection path | event |
site-id | ID of the site the data belongs | 123456789 |
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" }}] |
note
Don't hesitate to read our collection methods article to find the collection domain that has been assigned to you.
You can also use a custom domain thanks to our CDDC.
Example
Endpoint:
https://your.collection.domain/event?s=123456789&idclient=9e8d6d5f-143a-4a21-a7d5-7348b56e130d
Body:
{
"events": [
{
"name": "event.name",
"data": {
"property": "value",
"property2": "value"
}
}
]
}
Property type
info
In your Data Model, a property is tied to a specific type. When you tag your properties, this type must be the same.
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.
Example:
"data": {
...
"f:product_price": "12.50",
...
}
--> Even if the JSON type is string, we will process it as a float.
Date
Properties ending with _date
, _utc
, _timestamp
and _ts
are automatically casted as dates if the value whether:
- is a Timestamp in seconds
- complies with the RFC 3339 standard
YYYY-MM-DDTHH:mm:ssZ
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 |
Contextual properties
Some properties give insights on the context
Property | Description | Type | Example |
---|---|---|---|
previous_url | Previous page url | string | "https://www.piano.io/" |
device_timestamp_utc | Device timestamp UTC in seconds | int | 1648753357 |
event_collection_platform | Collection platform used | string | "api" |
event_collection_version | Version of the collection platform | string | "2" |
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 |
Marketing campaigns
In order to track marketing campaigns, you can use the following properties
Property | Description | Type | Example |
---|---|---|---|
src_medium (mandatory) | Campaign medium | string | "sea" |
src_campaign (mandatory) | Campaign name | string | "winter2022" |
src_creation | Campaign creation | string | "main" |
src_variant | Campaign variant | string | "blue" |
src_format | Campaign format | string | "440x300" |
src_type | Campaign type | string | "direct" |
You can also check your data model to see other properties linked to marketing campaigns.
Users
If you want to track your authentified users, we offer specific properties
Property | Description | Type | Example |
---|---|---|---|
user_id | User identifier | string | "WEB-192203AJ" |
user_category | User category | string | "premium" |