Javascript
Before I start
Piano Analytics SDKs have been designed for the Piano Analytics solution. Data sent through these SDKs will not be processed within the Analytics Suite 2.
"xtor" marketing campaigns syntax will not be recognized anymore. Please use "at_" instead.
Load the library
The first step to use our SDK is to load the JS file. You have two ways to do this:
CDN
You can load the library from https://tag.aticdn.net/piano-analytics.js:
<script type="text/javascript" src="https://tag.aticdn.net/piano-analytics.js"></script>
Download
You can also download the file from Github and upload it on your own server.
Configuration
In order to setup your tracking, you need to set the configuration of the library.
To do this, we offer two configuration methods depending on what you want to setup.
Basic configuration
pa.setConfiguration(configurationKey, configurationValue);
// or
pa.setConfigurations(configurationObject)
We recommend setting the configuration within the <head> of your page.
Here is the minimal configuration required:
pa.setConfiguration("site", 123456789); // your site id
pa.setConfiguration("collectDomain", "https://logsx.xiti.com"); // your collection domain
// or
pa.setConfigurations({
site: 123456789,
collectDomain: "https://logsx.xiti.com"
});
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.
Here are the available configurations:
| Category | Name | Description | Type | Value | More info |
|---|---|---|---|---|---|
| Global | collectDomain | Collection domain | string | "https://logsx.xiti.com" | View |
| Global | site | Site id | int | 123456789 | View |
| Global | path | Request path | string | "event" | |
| Global | addEventURL | Automatically adds a page_url property to all events, containing the URL of the current page | string | "false", "withoutQS" (default), "true" | |
| Privacy | sendEventWhenOptout | Do you want to send events when optout? | boolean | true (default), false | |
| Campaign | campaignPrefix | Choose with an order of priority the type of campaign to be collected | array | ["at_"] | View |
| Campaign | enableUTMTracking | UTM parameters collected as properties | boolean | true (default), false | View |
SDK configuration
This method is ran asynchronously and override SDK configuration.
You have to define it before SDK's loading.
window._pac = window._pac || {};
<script type="text/javascript" src="https://tag.aticdn.net/piano-analytics.js"></script>
We recommend setting the configuration within the <head> of your page.
Here an example of what you can configure:
window._pac = window._pac || {};
_pac.cookieDomain = '.mysite.com';
_pac.privacyDefaultMode = 'no-consent';
<script type="text/javascript" src="https://tag.aticdn.net/piano-analytics.js"></script>
Here are the available configurations:
| Category | Name | Description | Type | Value | More info |
|---|---|---|---|---|---|
| Global | cookieDomain | Domain of cookie deposit | string | "mysite.com" (current domain by default) | |
| Global | cookieSameSite | "SameSite" flag in cookies in client-side | string | "lax" (default), "none", "strict" | |
| Global | cookieSecure | "Secure" flag in cookies in client-side cookies | boolean | true (default), false | |
| Global | encodeStorageBase64 | Storage value encode (base64) | boolean | true, false (default) | |
| Global | queueVarName | Variable name used for queuing | string | "_paq" (default) | View |
| Privacy | privacyDefaultMode | Privacy mode by default | string | "optin" (default) | View |
| Storage | storageLifetimePrivacy | Lifetime Storage Privacy value | int | 395 (days) | View |
| Storage | storageLifetimeUser | Lifetime Storage User value | int | 395 (days) | View |
| Storage | storageLifetimeVisitor | Lifetime Storage Visitor value | int | 395 (days) | View |
| Storage | visitorStorageMode | Relative or fixed cookie lifetime value for visitor | string | "fixed" (default), "relative" | |
| Visitor Policy | isVisitorClientSide | Is cookie deposit client side ? If false, server side | boolean | true (default), false |
All configurations in "Basic configuration" are compatible with "SDK configuration" method.
Asynchronous tagging
The object _paq can be used to push commands in a queue, executed as soon as the tracker is loaded.
Each command is represented by an array pushed to the queue:
_paq.push([command, (... args)]);
The first element of the array represent the tracker's method to call (e.g.: sendEvent, setProperty, setUser...). The following elements are the method's arguments.
Example:
let _paq = window._paq || [];
_paq.push(['setUser', 'ID18859', 'Premium user', true]);
_paq.push(['sendEvent', 'page.display', {"page": "homepage", ...}]);
In some cases, you could need to change the name of the variable used for queuing asynchronous calls (e.g.: Matomo conflict). This can be changed thanks to the configuration key queueVarName.
window._pac = window._pac || {};
_pac.queueVarName = '_paqueue'; // set the queue variable name
window._paqueue = window._paqueue || [];
_paqueue.push(['sendEvent', 'page.display', {"page": "homepage", ...}]);
Piano Cross-product integration
Since v6.7.0, PA JS SDK integrates native synchronization with other Piano products SDKs.
This includes automatic retrieving of a common visitor ID, pageview ID, user access and content properties.
Content properties
In order to set the content properties, you can either do it through Composer implementation, or through PA SDK:
// set one content property
pa.setContentProperty('tags_array', ['world','politics']);
// or set multiple properties at once
pa.setContentProperties({
'tags_array': ['world','politics'],
'publication_date': 1669109350
});
When using these methods, content_ prefix is automatically added to the property key.
Specification
Piano Analytics Javascript SDKs are based on the sendBeacon browser API.
Please refer to the documentation if you want more information.
Changelog
You can find the Javascript changelog directly on GitHub.