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

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"
}
}
note

Please note that in HTTP requests, an array of events is required.

POST

important

Please note that we highly recommend using POST requests.

Endpoint:

https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>
HeaderValue
Content-Typetext/plain

Body:

{
"events": <event-array>
}
VariableDescriptionExample
collection-domainCollection endpoint for your organizationyour.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"
}
}
]
}

GET

Pattern

https://<collection-domain>/<path>?s=<site-id>&idclient=<visitor-id>&events=[<events-array>]
VariableDescriptionExample
collection-domainCollection endpoint for your organizationyour.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

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_ or visit_
  • 40 characters max

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 date following this pattern: YYYYMMDD or YYYY-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 and 1.0e15

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

Standard properties

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"

Application Lifecycle

In order to measure your application lifecycle (mobile oriented), here are the dedicated properties

PropertyDescriptionTypeExample
app_scSession countinteger12
app_dslsDays since last sessioninteger2
app_dsfsDays since first sessioninteger48
app_sessionidSession IDstring"a6de0f1c-667b-4219-b747-3fe39a0facc9"
app_fsdFirst session date (YYYYMMDD)string"20220401"
app_fsdauFirst session date after update (YYYYMMDD)string"20230125"
app_scsuSession count since updateinteger3
app_dsuDays since updateinteger10

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 value false in your events
  • max body size is set to 500 kB

Server-side Cookies management

info

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.