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
The event object is composed of two properties, while name
represents the event, data
is another object containing different the properties and values attached to the event.
{
"name": "event.name",
"data": {
"property": "value",
"property2": "value"
}
}
Please note that in HTTP requests, an array of events is required.
GET
Pattern
https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&events=[<events-array>]
Variable | Description | Example |
---|---|---|
collection-domain | Collection endpoint for your organization | 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 |
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 organization | 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" }}] |
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 key rules
The property key must follow some 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_
- 40 characters max
Property type
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 date following this pattern:
YYYYMMDD
orYYYY-MM-DD
- is a Timestamp in seconds
1660027175
(if you need milliseconds, use decimals:1660027175.475
) - complies with the RFC 3339 standard
YYYY-MM-DDTHH:mm:ssZ
Limits
Our data model imposes limits:
- string: 255 characters
- array of strings: 20 strings of 255 characters
- integer: int64
- decimal: between
-1.0e15
and1.0e15
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 |
Standard properties
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" |
Application Lifecycle
In order to measure your application lifecycle (mobile oriented), here are the dedicated properties
Property | Description | Type | Example |
---|---|---|---|
app_fs | First session? | boolean | false |
app_fsau | First session after update? | boolean | true |
app_sc | Session count | integer | 12 |
app_dsls | Days since last session | integer | 2 |
app_dsfs | Days since first session | integer | 48 |
app_sessionid | Session ID | string | "a6de0f1c-667b-4219-b747-3fe39a0facc9" |
app_fsd | First session date (YYYYMMDD ) | string | "20220401" |
app_fsdau | First session date after update (YYYYMMDD ) | string | "20230125" |
app_scsu | Session count since update | integer | 3 |
app_dsu | Days since update | integer | 10 |
Technical specifications
Our collection API has some technical specifications:
- HSTS header is automatically set on HTTPS requests, forcing a secure collection even from an unencrypted (HTTP) request
- support of TLS 1.0+, to ensure maximum browser compatibility
- use of dynamic IPs, do not rely on IP filtering
- collection IPs lifetime vary. Implementation must refresh DNS cache to respect TTL value (60 seconds) and spread the traffic across all IPs
- bot detection can be ignored by adding the boolean property
bot_detection
with the valuefalse
in your events
Server-side Cookies management
Please refer to storage documentation to view our server-side cookies specifications.
If the incoming request does not include an idclient
querystring parameter or an already existing server-side cookie, we will automatically redirect (302 Found
on GET
requests, 307 Temporary Redirect
on POST
requests) to set the server-side cookies. This redirection will upgrade to HTTPS in case of incoming HTTP request, leading to HSTS header to be set.