Skip to main content

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.

attention

"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

We offer a delivery of every versions of our JS SDK on our CDN, the file URL follow this pattern: https://tag.aticdn.net/js-sdk/piano-analytics-<version.number>.js.

<script type="text/javascript" crossorigin="anonymous" src="https://tag.aticdn.net/js-sdk/piano-analytics-6.10.0.js"></script>

You can find a list of all our JS SDK versions available from Github releases page.

Available files

6.11.0

CDN URL:
https://tag.aticdn.net/js-sdk/piano-analytics-6.11.0.js
SHA384 SRI checksum:
integrity="sha384-nhX81g4O71/bhU3OOjG/LNU1UEWbSiX5XmQjav305lwJ+AefpLvXlljFTQCiYRtr"
Source code:

6.10.0

CDN URL:
https://tag.aticdn.net/js-sdk/piano-analytics-6.10.0.js
SHA384 SRI checksum:
integrity="sha384-PL0eZkca1gTr2Nc5Yfqd8UjBbPrnPlHs+7kK5uYr8drGSYakwbxpKpZcBMOo0fcb"
Source code:

6.9.0

CDN URL:
https://tag.aticdn.net/js-sdk/piano-analytics-6.9.0.js
SHA384 SRI checksum:
integrity="sha384-LfRGPrHt/AQDJMqXziuwkESc/13xdRyJHgzcTjDOsv1C8Vbh4yM0jevVm4zUjADC"
Source code:
View all available files →

You can also load the latest version of our JS SDK from https://tag.aticdn.net/piano-analytics.js:

<script type="text/javascript" crossorigin="anonymous" src="https://tag.aticdn.net/piano-analytics.js"></script>
attention

Using this common file will lead to automatic SDK versions upgrade. If you need to have control over the version used, please use another library loading solution.

Download

You can also download the file from Github and host it on your own side.

info

If you want to stay updated with our SDK releases, please subscribe to it on Github directly:

subscribe to Github releases

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

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://<xxxxxxx>.pa-cd.com"); // your collection domain

// or

pa.setConfigurations({
site: 123456789,
collectDomain: "https://<xxxxxxx>.pa-cd.com"
});
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.

Here are the available configurations:

CategoryNameDescriptionTypeValueMore info
GlobalcollectDomainCollection domainstring"https://<xxxxxxx>.pa-cd.com"View
GlobalsiteSite idint123456789View
GlobalpathRequest pathstring"event"
GlobaladdEventURLAutomatically adds a event_url_full property to all events, containing the URL of the current page. Was page_url on < 6.10.0string"false", "withoutQS" (default), "true"
GlobalsendEmptyProperties>= 6.9.0 Allow sending properties with an empty value (empty string or undefined)stringfalse, true (default)
PrivacysendEventWhenOptoutDo you want to send events when optout?booleantrue (default), false
CampaigncampaignPrefixChoose with an order of priority the type of campaign to be collectedarray["at_"]View
CampaignenableUTMTrackingUTM parameters collected as propertiesbooleantrue (default), falseView
GlobalallowHighEntropyClientHints>= 6.9.0 Allow retrieving of high entropy client hintsbooleantrue (default), falseView

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" crossorigin="anonymous" src="https://tag.aticdn.net/piano-analytics.js"></script>
tip

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" crossorigin="anonymous" src="https://tag.aticdn.net/piano-analytics.js"></script>

Here are the available configurations:

CategoryNameDescriptionTypeValueMore info
GlobalcookieDomainDomain of cookie depositstring"mysite.com" (current domain by default)
GlobalcookieSameSite"SameSite" flag in cookies in client-sidestring"lax" (default), "none", "strict"
GlobalcookieSecure"Secure" flag in cookies in client-side cookiesbooleantrue (default), false
GlobalencodeStorageBase64Storage value encode (base64)booleantrue, false (default)
GlobalqueueVarNameVariable name used for queuingstring"_paq" (default)View
PrivacyprivacyDefaultModePrivacy mode by defaultstring"optin" (default)View
StoragestorageLifetimePrivacyLifetime Storage Privacy valueint395 (days)View
StoragestorageLifetimeUserLifetime Storage User valueint395 (days)View
StoragestorageLifetimeVisitorLifetime Storage Visitor valueint395 (days)View
StoragevisitorStorageModeRelative or fixed cookie lifetime value for visitorstring"fixed" (default), "relative"
Visitor PolicyisVisitorClientSideIs cookie deposit client side ? If false, server sidebooleantrue (default), false
note

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", ...}]);
note

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.

SPA

In order to refresh the pageview_id in your SPA, you can call the method pa.refresh() to regenerate the page context.

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
});
note

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.

Content Security Policy (CSP)

Configure your CSP settings:
SDK loading source

The following directives are needed in the CSP to use this setup:

script-src: 'unsafe-inline' https://tag.aticdn.net
connect-src: https://log.xiti.com

Changelog

You can find the Javascript changelog directly on GitHub.