Skip to main content

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>
VariableDescriptionExample
collection-domainCollection endpoint for your organisationyour.collection.domain
pathCollection pathevent
site-idID of the site the data belongs123456789
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
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>
}
VariableDescriptionExample
collection-domainCollection endpoint for your organisationyour.collection.domain
pathCollection pathevent
site-idID of the site the data belongs123456789
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" }}]
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.

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

Contextual properties

Some properties give insights on the context

PropertyDescriptionTypeExample
previous_urlPrevious page urlstring"https://www.piano.io/"
device_timestamp_utcDevice timestamp UTC in secondsint1648753357
event_collection_platformCollection platform usedstring"api"
event_collection_versionVersion of the collection platformstring"2"
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

Marketing campaigns

In order to track marketing campaigns, you can use the following properties

PropertyDescriptionTypeExample
src_medium (mandatory)Campaign mediumstring"sea"
src_campaign (mandatory)Campaign namestring"winter2022"
src_creationCampaign creationstring"main"
src_variantCampaign variantstring"blue"
src_formatCampaign formatstring"440x300"
src_typeCampaign typestring"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

PropertyDescriptionTypeExample
user_idUser identifierstring"WEB-192203AJ"
user_categoryUser categorystring"premium"