Javascript
Introduction
The Piano Analytics JavaScript SDK is the most popular way to implement data collection on websites. This lightweight library enables you to track user interactions, page views, conversions, and custom events with minimal setup.
What you'll learn in this guide:
- How to load and configure the JavaScript SDK
- Different implementation methods
- Basic and advanced configuration options
- How to send events and track user behavior
Prerequisites:
- Basic knowledge of HTML and JavaScript
- Access to your Piano Analytics site ID and collection domain
- Ability to modify your website's code
"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 delivery of our JS SDK on our CDN. You can choose between different implementation approaches:
Standard implementation (>= 6.16.0)
Our recommended approach combines library loading and configuration in a single, self-contained script:
(function (_config) {
var script = document.createElement("script");
script.src = "https://tag.aticdn.net/piano-analytics.js";
script.async = true;
script.crossorigin = "anonymous";
script.dataset.config = JSON.stringify(_config);
document.head.appendChild(script);
})({
site: 123456789,
collectDomain: "https://xxxxxxx.pa-cd.com",
consentDefaultMode: "opt-in",
});
- Single script: No need to manage separate loading and configuration steps
- Asynchronous loading: Non-blocking script execution
- Configuration via data attribute: Clean configuration management
Replace 123456789
with your site ID and xxxxxxx.pa-cd.com
with your collection domain. You can customize any configuration parameters within the _config
object.
To use a specific version, replace piano-analytics.js
with js-sdk/piano-analytics-<version.number>.js
in the script source (>= 6.16.0).
Traditional script tag
You can also load our SDK using traditional HTML script tags:
<script
type="text/javascript"
crossorigin="anonymous"
src="https://tag.aticdn.net/piano-analytics.js"
></script>
Available files
We offer delivery of every version of our JS SDK on our CDN, the file URL follows this pattern: https://tag.aticdn.net/js-sdk/piano-analytics-<version.number>.js
.
You can also load the latest version from https://tag.aticdn.net/piano-analytics.js
.
(function (_config) {
var script = document.createElement("script");
script.src = "https://tag.aticdn.net/js-sdk/piano-analytics-6.16.3.js";
script.async = true;
script.crossorigin = "anonymous";
script.dataset.config = JSON.stringify(_config);
document.head.appendChild(script);
})({
site: 123456789,
collectDomain: "https://xxxxxxx.pa-cd.com",
consentDefaultMode: "opt-in",
});
<script type="text/javascript" crossorigin="anonymous" src="https://tag.aticdn.net/js-sdk/piano-analytics-6.16.3.js"></script>
You can find a list of all our JS SDK versions available from Github releases page.
Available files
6.16.3
https://tag.aticdn.net/js-sdk/piano-analytics-6.16.3.js
integrity="sha384-A97bdkrpKedzwN4jashR/QRCQWukpkoKezGy56rrXLVlgtKCSnba2+eKDPU2XF9t"
6.16.2
https://tag.aticdn.net/js-sdk/piano-analytics-6.16.2.js
integrity="sha384-cVVcQekx/78gr+aaD/HlCCFLQAMEMKdnuwrRFYZeDGB3/L1dzTOx+fW0+47DRsf4"
6.16.1
https://tag.aticdn.net/js-sdk/piano-analytics-6.16.1.js
integrity="sha384-Ycef5N78HX10m2bPKhjHG8lLnb+5cCoy1YqusH/WhSzN6jVkU42+KFagvqc3FWzO"
Using the latest version file (piano-analytics.js
) will lead to automatic SDK versions upgrade. If you need to have control over the version used, please use versioned files instead.
Download
You can also download the file from Github and host it on your own side.
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);
Here is the minimal configuration required:
try {
// Basic configuration method
pa.setConfiguration("site", 123456789); // your site id
pa.setConfiguration("collectDomain", "https://<xxxxxxx>.pa-cd.com"); // your collection domain
// or bulk configuration (recommended)
pa.setConfigurations({
site: 123456789,
collectDomain: "https://<xxxxxxx>.pa-cd.com",
});
} catch (error) {
console.error("Piano Analytics configuration error:", error);
// Handle configuration failure gracefully
}
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://<xxxxxxx>.pa-cd.com" | View |
Global | site | Site id | int | 123456789 | View |
Global | path | Request path | string | "event" | |
Global | addEventURL | Automatically adds a event_url_full property to all events, containing the URL of the current page. Was page_url on < 6.10.0 | string | "false" , "withoutQS" (default), "true" | |
Global | sendEmptyProperties | ≥ 6.9.0 Allow sending properties with an empty value (empty string or undefined ) | boolean | true (default), false | |
Global | enableAutomaticPageRefresh | ≥ 6.12.0 Allow the SDK to automatically manage page context refresh | boolean | true (default), false | View |
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 |
Global | allowHighEntropyClientHints | ≥ 6.9.0 Allow retrieving of high entropy client hints | 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"
crossorigin="anonymous"
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"
crossorigin="anonymous"
src="https://tag.aticdn.net/piano-analytics.js"
></script>;
These configurations must be set before loading the SDK:
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 | ≥ 6.4.0 Variable name used for queuing | string | "_paq" (default) | View |
Global | globalVarName | ≥ 6.12.0 Variable name used for global instance | string | "pa" (default) | |
Privacy | privacyDefaultMode | Privacy mode by default | string | "optin" (default) | View |
Privacy | enableExtendedOptout | ≥ 6.13.0 Enable extended opt-out feature | boolean | false (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 || [];
try {
_paq.push(["setUser", "ID18859", "Premium user", true]);
_paq.push(["sendEvent", "page.display", { page: "homepage" }]);
} catch (error) {
console.error("Piano Analytics error:", error);
}
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.
Automatic page context management
Since version 6.12.0
, the SDK automatically refresh the page context when a second page.display
event is sent on the same instance (configuration enableAutomaticPageRefresh
: true
by default).
Only one of both (pa.refresh()
or automatic detection) is possible for an implementation. Only the first one encountered on an instance will be available for the lifetime of the instance.
Content properties
Since 6.7.0, the SDK automatically sends content properties from HTML markup. Please check this page for expected markup.
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("type", "article");
// -> content_type = 'article'
// or set multiple properties at once
pa.setContentProperties({
type: "article",
publication_date: 1669109350,
});
// -> content_type = 'article'
// -> content_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.
Content Security Policy (CSP)
Configure your CSP settings: | |
The following directives are needed in the CSP to use this setup:
script-src: 'unsafe-inline' https://tag.aticdn.net
connect-src: https://xxxxxxx.pa-cd.com
Changelog
You can find the Javascript changelog directly on GitHub.
If you want to stay updated with our SDK releases, please subscribe to it on Github directly: