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.

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

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

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 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.

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 value false in your events

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.