Skip to main content

Collection API

The Piano Analytics Collection API enables direct transmission of analytics events via HTTP requests, offering a flexible solution for environments where SDK integration is not feasible.​

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

Programming Examples​

async function sendPianoAnalyticsEvent(events, siteId, visitorId, collectionDomain) {
const endpoint = `https://${collectionDomain}/event`;
const params = new URLSearchParams({
s: siteId,
idclient: visitorId,
});

try {
const response = await fetch(`${endpoint}?${params}`, {
method: "POST",
headers: {
"Content-Type": "text/plain",
},
body: JSON.stringify({ events }),
});

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

console.log("Events sent successfully");
return await response.text();
} catch (error) {
console.error("Failed to send events:", error);
// Implement retry logic or fallback here
throw error;
}
}

// Usage
sendPianoAnalyticsEvent(
[
{
name: "page.display",
data: {
page: "Homepage",
page_chapter1: "Main",
},
},
],
"123456789",
"9e8d6d5f-143a-4a21-a7d5-7348b56e130d",
"your.collection.domain"
);

GET​

Endpoint​

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 visitor9e8d6d5f-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)

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

TLS policy​

If you use a custom domain for your collection (CDDC), you can request one of the following specific TLS configuration.

Available policies:

SSLv3TLSv1TLSv1_2016TLSv1.1_2016TLSv1.2_2018TLSv1.2_2019TLSv1.2_2021
Supported SSL/TLS protocols
TLSv1.3♦♦♦♦♦♦♦
TLSv1.2♦♦♦♦♦♦♦
TLSv1.1♦♦♦♦
TLSv1♦♦♦
SSLv3♦
Supported TLSv1.3 ciphers
TLS_AES_128_GCM_SHA256♦♦♦♦♦♦♦
TLS_AES_256_GCM_SHA384♦♦♦♦♦♦♦
TLS_CHACHA20_POLY1305_SHA256♦♦♦♦♦♦♦
Supported RSA ciphers
ECDHE-RSA-AES128-GCM-SHA256♦♦♦♦♦♦♦
ECDHE-RSA-AES128-SHA256♦♦♦♦♦♦
ECDHE-RSA-AES128-SHA♦♦♦♦
ECDHE-RSA-AES256-GCM-SHA384♦♦♦♦♦♦♦
ECDHE-RSA-CHACHA20-POLY1305♦♦♦♦♦♦♦
ECDHE-RSA-AES256-SHA384♦♦♦♦♦♦
ECDHE-RSA-AES256-SHA♦♦♦♦
AES128-GCM-SHA256♦♦♦♦♦
AES256-GCM-SHA384♦♦♦♦♦
AES128-SHA256♦♦♦♦♦
AES256-SHA♦♦♦♦
AES128-SHA♦♦♦♦
DES-CBC3-SHA♦♦
RC4-MD5♦

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 for incoming HTTP requests, causing the HSTS header to be set.