Free training

Free Piano Analytics Training – 2026

Are you looking for a modern, reliable analytics solution that complies with European privacy standards? Piano Analytics is an alternative increasingly used by companies wishing to regain control over their data compared to our legendary Google Analytics. Piano Analytics is one of the tools exempted from consent by the CNIL, making it a strong argument for comprehensive, privacy-first data collection.

24 min read
11 chapters
No email address required

Piano Analytics: Step-by-Step Implementation

Are you looking for a modern, reliable analytics solution that complies with European privacy standards? Piano Analytics is an alternative increasingly used by companies wishing to regain control over their data compared to our legendary Google Analytics. Piano Analytics is one of the tools exempted from consent by the CNIL, making it a strong argument for comprehensive, privacy-first data collection.

This training course has been designed to help you set up Piano Analytics, from project preparation through to analysis of the data collected. Unlike Piano's boring (and hyper-complex, by the way) product documentation, this training course offers a practical, operational approach focused on the concrete challenges of analytics projects: account structuring, data model construction, tracking configuration, rights management, GDPR compliance, TMS and technical acceptance.

Each section of this guide has been designed to meet the needs of professionals who are undertaking a redesign, migration, or initial implementation of Piano Analytics.

What you'll learn

How to structure your Piano Analytics account effectively
How to organize your events, variables and properties
How to implement Piano Analytics on a site (classic or SPA)
How to integrate Piano into your TMS (TagCommander or GTM)
How to test, validate and correct your tagging plan
And how to comply with legal obligations relating to consent

1. Introduction

Piano Analytics is an analytics solution developed by Piano.io, successor to AT Internet (SmartTag). It is based on a modern, centralized architecture, where the concepts of unified data model, privacy by design, flexible implementation and first-party collection are central.

Unlike Google Analytics, Piano explicitly separates the levels of organization, tracking and rights management, which implies a rigorous upstream scoping phase. This training course will help you to structure, implement and validate this analytics foundation in a reliable and scalable way.

2. Structuring your Piano Analytics account

2.1 Choosing the right architecture for your organization

Account structure is the foundation of any Piano Analytics implementation. Poor architecture leads to severe limitations on collection, analysis, governance and scalability. So it's essential to take the time to frame your model before deployment.

The building blocks

Organization: root level, equivalent to the "account" in GA. The data model is defined centrally.
Level 1 sites: main unit of measurement (often a domain or an application). This is where hits are sent and cookies are set.
Level 2 sites: logical subdivisions of a site (e.g. sections, sub-domains), which can be filtered in the interface but do not collect data independently.
Site groups: sets of level 1 sites grouped together for aggregate analysis.
Virtual sites: reprocessed duplicates of data to analyze the same perimeter from alternative angles (Matomo / GA roll-up equivalent).

Case study: multi-domain or multi-structure?

Before allocating your sites, ask yourself the following questions:

Are my domains totally independent (e.g. different brands)? → One level 1 site per domain.
Do my subdomains need to be analyzed separately? → Level 2 sites depending on deduplication requirements.
Do I need a unified view for all scopes? → Use site groups.
Does each entity have its own analytics teams? → Consider delegations (see below).

2.2 User access and role management

Piano Analytics is based on a hierarchical rights management system, which allows great flexibility but requires strict governance to prevent abuses.

The 3 Levels of Rights Assignment

Organization: Global access to all sites. Administrator can manage all users.
Delegation: Autonomous intermediate unit on a subset of sites (by BU, country, etc.).
Group: Grouping of users with rights defined by role on one or more sites.

👤 Standard user roles

Role	Description
Document Reader	Read-only access to reports, exports and In-Page Analytics.
Business User	Includes all Document Reader rights, plus access to Explorer for interactive data viewing.
Analyst	Business Analyst rights, plus the ability to create segments, metrics and reports. Read access to Data Model and API.
Advanced Analyst	Analyst rights, with additional capabilities: tagging configuration (collection portal), data flow management, and advanced solution customization options.
Data Supervisor	The only role other than administrators that is authorized to modify the data model structure (creating, editing, and deleting properties and events).
Administrator	All rights, of course
Custom	Customized role for freely combining tools (e.g. reading + tagging configuration).

Good governance practices

Limit the number of Data Supervisors and Administrators to the absolute minimum.
Formalize a process for creating/modifying user accounts.
Document assigned roles and associated sites.
Never give full access to external profiles (agencies, service providers).

3. Design a robust data model

3.1 What is the Data Model?

The Piano Analytics data model is the set of properties (dimensions) and events that you collect from all your sites and measurements (enrichment options = data import). It is defined at the organization level and therefore applies to all linked sites. Unlike Google Analytics, this is a centralized and unified model.

The Data Model (excluding measurements) is structured as follows:

Properties: custom or native dimensions (e.g. page, device, user type).
Events: measured actions (e.g. page.display, click.navigation, transaction.confirmation).

Limits to be aware of: you can create an unlimited number of custom events, but the number of custom properties is limited to 1000 per organization.

3.2 Preparing the data model: scoping and workshops

Before any property or event is created, a scoping phase is essential. It must bring together business and technical stakeholders to:

Identify the KPIs and business events that are really worth measuring.
Identify duplicates and inconsistencies (e.g. same data named differently on several sites).
Align data model structure with expected analysis cases in Explorer or Data Query.

It is recommended to formalize a shared reference document (Notion, Excel, Airtable, Sheets...) with:

A Properties tab (display name, type, technical key, category, creation date).
An Events tab (name, trigger, description, scope, categories).
A possible mapping with the dimensions/events used in the previous tool (e.g. GA).

3.3 Creating and managing custom properties

From the Piano interface (Data Management > Properties), you can create a new property. You'll need to fill in:

Label: name readable in the interface (Explorer, Data Query...)
Description: very useful for avoiding duplication or misinterpretation
Type: string, integer, date, boolean, etc.
Property key: identifier used in tags and APIs (irreversible once validated)
Category(ies): to filter and organize in the interface

⚠️ Attention: once a property has been validated, it is fixed: only its description can be modified. If an error is made on the key or type, the only option is to hide the property (it remains accounted for).

3.4 Creating custom events

Creating an event is more flexible than creating a property: you enter:

Event name (e.g. hello)
Description (trigger function)
Scope: on-site or off-site (e.g. CRM, server-side...)
Categories (ecommerce, navigation, user...)

3.5 Data reprocessing & extraction/concatenation

Piano Analytics allows you to modify, extract or clean data after collection at property level, via processing rules. This is done in the interface, in the configuration of each property, in the "Processing" tab:

Correction: clean up a poorly formatted or inconsistent field.
Mapping: transform an internal code into a readable label via a mapping table.
Deletion: empty incorrect data.
Extraction / Concatenation: extract a URL parameter or concatenate multiple fields.

Data import

In addition to the data collected via the SDK, Piano allows you to import data (CSV, SFTP or API files) at organization level. This is the "Measurements” feature in Piano Analytics (Data Management > Data Model).

This is a method of importing aggregated numerical data linked to a given period (day, hour, etc.), enabling analytical data to be contextualized, for example by cross-referencing sales with the weather or the number of subscribers on social networks.

Each Measurement is defined by a key, one or more values (e.g. temperature, humidity), and can be enriched with properties (such as region or device type). Data can be sourced from external APIs (such as Google Search Console), CSV files, or third-party tools (such as Adverity), then sent via Piano's dedicated API. Once created, Measurements can be used to generate metrics for use in interfaces such as Explorer or Workspaces.

Granularity, scope (site or organization), and temporal aggregation must be well defined. Data is quickly visible, except in the case of caches, and can be easily corrected. Certain fine-grained properties (eg. event_time, visitor_id) are prohibited.

🧠 Global best practices

Prefix the names of your events and properties (e.g.: ecom.product_id, ux.page_type).
Have a naming convention for properties (e.g. prefix the name by business area)
Hide obsolete properties to keep the model clear.

4. Technical implementation of Piano Analytics

4.1 Loading the Piano Analytics library

The first step in the integration process is to load the JS library of Piano Analytics on your site. Three methods are available:

CDN library (latest version): https://tag.aticdn.net/piano-analytics.js
Versioned CDN library: https://tag.aticdn.net/js-sdk/piano-analytics-<version.number>.js
Self-hosted library: available on Piano's GitHub

You can find a list of all available JS SDK versions on the Github versions page. https://github.com/at-internet/piano-analytics-js/releases

Once the library is loaded, there are two configuration methods:

Basic Method (Synchronous)

<script type="text/javascript" src="https://tag.aticdn.net/piano-analytics.js"></script>
<script>
pa.setConfigurations({
  // Obligatoire. Domaine de collecte des données (à adapter selon ta configuration réelle)
  collectDomain: "https://<xxxxxxx>.pa-cd.com",

  // Obligatoire. Mode de confidentialité par défaut (important pour le RGPD)
  // "optin" : pas de suivi sans consentement / "no-consent" : mode cookieless / "exempt" : collecte minimale légale / "optout" : refus explicite
  privacyDefaultMode: "exempt",

  // Obligatoire. ID du site tel que configuré dans Piano Analytics
  site: 123456789,

  // Domaine de dépôt des cookies (par défaut = domaine actuel)
  cookieDomain: ".mysite.com";

  // Conseillé. Ajoute automatiquement une propriété event_url_full à chaque événement (utile pour les analyses de navigation)
  addEventURL: "true", // options : "true", "false", "withoutQS" (par défaut)

  // Conseillé. Gère automatiquement le rafraîchissement du contexte de page (utile pour les SPAs ou les changements dynamiques de page)
  enableAutomaticPageRefresh: true,

  // Par défaut mettre en false. Envoie tout de même les événements lorsque l'utilisateur est en optout (utile pour certaines analyses anonymisées ou mesures légales : extended optout)
  sendEventWhenOptout: true,
  enableExtendedOptout: true,

  // Conseillé. Liste des préfixes de campagnes à reconnaître dans l’URL. Bonnes pratiques : ["at_", "utm_"]
  campaignPrefix: ["at_", "utm_"],

  // Conseillé. Active la collecte automatique des paramètres UTM (utm_source, utm_medium, etc.)
  enableUTMTracking: true,

  // Pas utile car par défaut lax. Définition de la politique SameSite pour les cookies
  // "lax" recommandé (défaut), "strict" pour plus de sécurité, "none" avec Secure pour cross-domain
  cookieSameSite: "lax",

  // Active le flag "Secure" (requis si SameSite="none" ou sur HTTPS)
  cookieSecure: true,

  // Obligatoire. Durée de vie des cookies (13 mois conseillé) : identifiants de consentement, utilisateur et visiteur (en jours)
  storageLifetimePrivacy: 395,
  storageLifetimeUser: 395,
  storageLifetimeVisitor: 395,

  // Autorise la collecte des Client Hints enrichis (permet une meilleure détection navigateur/appareil, si disponible)
  allowHighEntropyClientHints: true
});
</script>

SDK Method (Asynchronous)

<script>
  window._pac = window._pac || {};

  // ID du site Piano Analytics
  _pac.site = 123456;

  // Mode de confidentialité par défaut (important pour le RGPD)
  // "optin" : pas de suivi sans consentement / "no-consent" : mode cookieless / "exempt" : collecte minimale légale / "optout" : refus explicite
  _pac.privacyDefaultMode = "exempt";

  // Domaine de dépôt des cookies (par défaut = domaine actuel)
  _pac.cookieDomain = ".mysite.com";

  // Définition de la politique SameSite pour les cookies
  // "lax" recommandé (défaut), "strict" pour plus de sécurité, "none" avec Secure pour cross-domain
  _pac.cookieSameSite = "lax";

  // Active le flag "Secure" (requis si SameSite="none" ou sur HTTPS)
  _pac.cookieSecure = true;

  // Durée de vie des cookies : identifiants de consentement, utilisateur et visiteur (en jours)
  _pac.storageLifetimePrivacy = 111;
  _pac.storageLifetimeUser = 111;
  _pac.storageLifetimeVisitor = 111;

  // Mode de durée de vie du cookie visiteur : "fixed" = durée glissante, "relative" = durée à partir de la première visite
  _pac.visitorStorageMode = "relative";

  // Active le mode "opt-out étendu" (ne stocke rien même si anonymisé)
  _pac.enableExtendedOptout = true;
  _pac.sendEventWhenOptout = true;

</script>

<!-- 📡 Chargement du SDK Piano Analytics -->
<script src="https://tag.aticdn.net/piano-analytics.js"></script>

Advice: place the library load in the <head> of your pages, with your main configurations (site, domain, privacy...)

4.2 Tagging methods

Piano Analytics offers two ways of sending events:

Direct Method

pa.sendEvent("page.display", {
  page: "homepage",
  page_type: "landing"
});

Asynchronous method (queue)

window._paq = window._paq || [];
_paq.push(["sendEvent", "page.display", {
  page: "homepage",
  page_type: "landing"
}]);

Which method to use depends on your technical and TMS stack. In general, the queue-based method is recommended for integrations via Tag Manager, but it is still not widely used, with the majority of users continuing to use pa.sendEvent as historically. My personal preference? None, both seem to be pretty similar if you don't need the queue logic.

4.3 Adding global properties

You can define properties that apply to all events according to their definition:

Single property

pa.setProperty("visitor_type", "logged_in", {
  persistent: true,
  events: ["page.*", "click.*"]
});

Multiple Properties in a Block

pa.setProperties({
  visitor_type: "logged_in",
  device_type: "mobile"
}, {
  persistent: true
});

Persistence allows these properties to be injected automatically into the next events sent, without having to repeat them.

4.4 Good tagging practices

Strictly observe the property type declared in the Data Model (e.g.: integer, string)
Using clear prefixes for your customized events (e.g: form.submit, product.add)
Check hits in the network console: filter on xiti or event
Do not use chapter concatenation (::) as in SmartTag. Piano requires separate fields.
Mandatory typing: some data must be strings (e.g., if a property uses a mapping table, it must be in string)

Common mistake: sending a transaction.id as an integer when it is defined as string in the model blocks transaction analysis!

4.5 Sending events with Piano Analytics SDK

Piano Analytics is based on an event-based architecture. This means that each action to be measured (page view, click, interaction, conversion...) must be sent via a named event, with associated properties.

There are two main methods:

pa.sendEvent(name, properties) for a single event
pa.sendEvents([{ name, data }, ...]) for several events at the same time

`pa.sendEvent()` — Send a single event

This is the most commonly used method. It is used in 90% of cases: page view, click, impression, conversion...

pa.sendEvent("page.display", {
  page: "homepage",
  page_chapter1: "accueil",
  environment: "production"
});

⚠️ Event name ("page.display" here) must correspond to an event defined in your data model. It can be native or customized.

`pa.sendEvents()` — Send multiple events at once

Useful when you want to trigger several events simultaneously, for example when confirming a purchase (order + products purchased).

pa.sendEvents([
  {
    name: "transaction.confirmation",
    data: {
      transaction_id: "ORDER123",
      cart_turnovertaxincluded: 89.90
    }
  },
  {
    name: "product.purchased",
    data: {
      product_id: "SKU-001",
      product: "Crème de jour",
      quantity: 1
    }
  },
  {
    name: "product.purchased",
    data: {
      product_id: "SKU-002",
      product: "Sérum nuit",
      quantity: 2
    }
  }
]);

Each item sent via pa.sendEvents must contain two keys:

name event name
data associated properties

💡 Recommendations

Use pa.sendEvent for simple and immediate cases
Choose pa.sendEvents in complex e-commerce or transactional scenarios
Avoid exceeding 20 simultaneous events in a single request
Respect the typing of each property (eg: string vs. integer)
Define persistent properties upstream, if certain data must be present on several events

All events that have been sent can be viewed via the Stream Inspector from Piano Analytics, to check that they have been correctly sent and structured.

📄 Page view

pa.sendEvent("page.display", {
  page_chapter1: "produits",
  page_chapter2: "marques",
  page_chapter3: "TEST",
  page: "page_xyz"
});

🖱 Click (action, navigation...)

pa.sendEvent("click.navigation", {
  click_chapter1: "header",
  click: "menu_boutique"
});

🛒 E-commerce transaction

pa.sendEvents([
  {
    name: "transaction.confirmation",
    data: {
      cart_id: "ORD-2024-0001",
      cart_currency: "EUR",
      cart_turnovertaxincluded: 79.99
    }
  },
  {
    name: "product.purchased",
    data: {
      cart_id: "LAPXXXX",
      product_id: "LAPXXXX", // mandatory property
      product: "Laptop AXCCCCC",
    }
  }
]);

5. Integrating Piano Analytics with a TMS

Integration via a TMS enables Piano Analytics to be deployed in a modular way, without directly modifying the site's source code. This facilitates maintenance, acceptance, governance and future upgrades.

5.1 Implementation with Tag Commander

Recommended steps

INIT tag: library loading + global configuration
Page display tag: basic event for all pages
Event tag: clicks, scroll, interaction (split if the naming convention is complex)
E-commerce tag: actions linked to the conversion funnel
Privacy tag: consent, optin/optout (if not managed elsewhere)

Recommended method: Free Input tag

Avoid limited templates: prefer "Free Input" tags with your own Piano script.

Example of an INIT (asynchronous) configuration – see above for more details

window._pac = window._pac || {};
_pac.site = 123456;
_pac.privacyDefaultMode = "no-consent";

Example of an event tag

_paq.push(["sendEvent", "click.navigation", {
  click: "btn_inscription"
}]);

Once you have created your tags:

Test them in the browser (Network tab, filter xitior filter pa-cd if new collection domain)
Deploy a version dedicated to acceptance testing
Test with Tag Inspector or by overriding the container's javascript.

5.2 Implementation with Google Tag Manager (GTM)

GTM is the most widely used tagging tool in digital ecosystems. Piano is implemented via:

Custom HTML tag (full script)
Community template (GTM gallery)

Example of a custom HTML tag

<script>
window._pac = window._pac || {};
_pac.site = 123456;
_pac.privacyDefaultMode = "no-consent";
</script>
<script src="https://tag.aticdn.net/piano-analytics.js"></script>

Official Piano Analytics Template

Import via the community gallery. Two elements are required:

A configuration variable (site ID, domain, privacy mode...)
One or more action tags (send event, set privacy...)

💡 Tip: Sequencing

The configuration tag (init) must be executed before any event tags (via the GTM sequencing function).

5.3 Server-Side tracking with CommandersAct X

CommandersAct X allows you to configure server-side collection to Piano Analytics, via the Collection API. This reduces browser dependency (cookies, adblock, JS).

Prerequisites

Client-side CommandersAct implementation (browser)
Creation of a Piano destination in the CommandersAct console
Configuration of mapping between CommandersAct events (e.g: purchase) and Piano (transaction.confirmation)

Special features

Add parameter visitor_privacy_mode in events to manage consent
Configure two destinations if you use hybrid measurement: user_consent = Piano and user_consent = Fonctionnement

Acceptance testing

Use the Event Inspector integrated with CommandersAct to view hits to Piano. Check that:

Site ID and collection domain are present
Events have the right names and properties
Data displayed correctly in Stream Inspector and Data Query

Note: full server-side without client (JS) doesn't count visits (no Piano cookies) → use it as a hybrid.

6. Tracking acceptance & validation

A Piano Analytics implementation is only reliable if it has been rigorously tested. This phase ensures that:

The solution is correctly initialized
Events are sent according to defined rules
Expected properties are correctly transmitted and populated
Privacy constraints (consent) are respected

6.1 Preparing acceptance testing

Create a validation checklist

Before testing, create a follow-up document listing:

Key pages and paths to test
Expected events (exact name, trigger conditions)
Expected properties for each event
Compliance with consent modes (opt-in, exempt, refusal)

Tip: use tools like Google Sheets, Notion or Airtable to track your tests by environment (DEV, PREPROD, PROD).

6.2 Technical validation tools

Browser console

Open the dev tools (F12 or right-click > Inspect)
Go to the Network tab
Filter on xiti , pa-cd or event?
Inspect the parameters in the Payload sub-tab

Chrome Extension: Piano Tag Inspector

Displays all Piano hits (page views, clicks...), with properties and event types.

Can be used in conjunction with Network
More legible display, useful for non-technical profiles

Google Tag Manager: Preview Mode

Check that Piano Analytics tags have been triggered
Inspect tags in the Tag Details section
Validate that the right variables are injected at the right time

Piano Analytics Interface

Stream Inspector: real-time display of events received
Data Query: data model exploration (properties, formats, values)

Please note: processing rules are only applied after collection → they are not displayed in front-end debugging tools.

7. Global best practices

7.1 Structure and governance

Frame the architecture from the outset: every wrong initial decision (single site too large, poorly thought-out data model) will have a lasting impact on your analyses.
Separate PROD and PREPROD: create separate test sites and avoid data pollution.
Limit critical access: only administrators and data supervisors should be able to create or modify the data model.
Formalize a property creation process: validate business requirements, typing, technical key, categories before saving.
Adopt a clear naming convention: standardize event, property and site names (eg: product.add_to_cart, form.submit_contact).

7.2 Documentation & collaboration

Maintain a centralized data model file: type, property, value, production date, link to tag...
Trace all additions/returns: version your template file with dates and validations
Document processing rules: any reprocessing (cleaning, mapping, enrichment) must be visible and commented on
Sharing access intelligently: avoid using generic or "super admin" accounts en masse, preferring targeted groups

7.3 Implementation & maintenance

Define a clear tagging plan: pathways, triggers, priorities
Test each tag before production: use Piano Tag Inspector, the console or Piano's internal tools
Respect typing: the slightest string/integer mismatch blocks processing
Centralize tracking errors: use an error sheet and ticketing logic if necessary
Follow a changelog: any change in the tagging or data model must be documented

7.4 Scalability and sustainability

Use virtual sites sparingly: beware of costs and double collection
Plan quarterly reviews: check data model, obsolete properties, processing rules
Adopt a modular approach: break down your implementation by tags/features to facilitate upgrades
Train your teams on a regular basis: project managers, analysts and techs need to understand how the Piano model works

In a nutshell: Successful implementation relies as much on a well-mastered technique as it does on solid governance and ongoing documentation. This guide provides you with the keys to structuring your Piano Analytics system over the long term.

8. Privacy & Hybrid measurement (CNIL exemption)

Opt-in: explicit user consent → complete collection authorized
Exempt: no explicit choice (abstention or refusal 1st/2nd level via CMP) → partial collection possible
Opt-out: explicit refusal (often 3rd level via management button) → no personal data collected

8.2 Hybrid measurement scenarios

Acceptance (opt-in): all cookies set, full collection enabled
Abstention (exempt): collection limited to necessary data, no marketing cookies
Refusal (opt-out): no cookies or other personal information is collected

To legally use the CNIL Exemption mode in France, it is imperative to follow the CNIL guide recommendations:

Sign the contractual appendix DPA ePrivacy with AT Internet
Request activation via your Customer Success Manager (CSM)
Apply all tagging restrictions defined by Piano Analytics (see below)
Receive a certificate of conformity provided by Piano after validation

Privacy Modes in Piano Analytics

With version 6.8 of the JavaScript SDK, Piano Analytics introduces a unified module: Consent Management.

Each visitor is associated with a visitor_privacy_mode and a visitor_privacy_consent to dynamically control data collection.

Mode	Cookie	Visitor ID	Consent	Collected data	Anonymization
optin	✅	GUID	true	all	❌
exempt	✅	❌	false	partial	✅
no-consent	❌	❌	false	limited	✅
optout	✅	❌	false	limited	✅
custom	personalized	personalized	variable	to configure	variable

Before sending an event, you must define the privacy mode with:

// Consentement utilisateur (CMP ou cookie banner)
if (userConsent === "optin") {
  pa.privacy.setMode("optin");
} else if (userConsent === "exempt") {
  pa.privacy.setMode("exempt");
} else {
  pa.privacy.setMode("optout");
}

Mode management via SDK

// Définir le mode actif
pa.privacy.setMode("optin");

// Obtenir le mode courant
const mode = pa.privacy.getMode();

Fine-grained inclusion/exclusion

Include identifiers if exempt:

pa.privacy.include.storageKeys(["pa_vid", "pa_uid"], ["exempt"]);

Other examples:

// Inclure "pa_vid" dans tous les modes (y compris "no-consent", "exempt", "optin", etc.)
pa.privacy.include.storageKey("pa_vid");

// Inclure "pa_uid" uniquement dans les modes "exempt" et un mode personnalisé "customMode"
pa.privacy.include.storageKey("pa_uid", ["exempt", "customMode"]);

// Inclure plusieurs clés dans tous les modes
pa.privacy.include.storageKeys(["pa_vid", "pa_uid"]);

// Inclure plusieurs clés uniquement dans les modes choisis
pa.privacy.include.storageKeys(["pa_vid", "pa_uid"], ["exempt"]);

Include properties according to privacy mode:

pa.privacy.include.property("article_category", ["exempt"], ["page.display"]);

Include events according to privacy mode:

pa.privacy.include.property("article_category", ["exempt", "customMode"]); // Will be included in selected modes

Exclude events according to privacy mode:

pa.privacy.exclude.events(["ecommerce.purchase"], ["optout"]);

Creating a customized Privacy Mode

pa.privacy.createMode("analytics_only", false);

This allows you to fully customize the SDK's behavior to align with your consent policy.

8.4 Buffer in exempt mode: minimizing the data collected

In exempt mode, only strictly necessary properties need be collected. Add them explicitly:

pa.privacy.include.properties(
  ['custom1','custom2','custom3','custom4'],
  ['exempt']
);

Best practices: avoid marketing or identifying properties (e.g. user_id, campaign, revenue...)

8.5 Automatic properties by mode

visitor_privacy_mode → indicates user mode (optin / exempt / optout)
visitor_privacy_consent → Boolean (true if optin)

These properties can be used in Data Query or dashboards to filter traffic according to consent status.

8.6 Exempt mode restrictions

No personal data, identifiers, user_id
No non-aggregated exports
No use of imported data (e.g. CRM)
No cross-checking between visits → cohorts only
Trackers limited to 13 months, IP anonymized (last byte masked)

⚠️ Please note: only anonymized aggregate data is retained. The attribution module is therefore only partially fed in exempt mode.

8.7 Marketing sources and exempt mode

Natural sources are preserved (referrer, search)
Campaigns marked with xtor are not interpreted → use at_*
The source type is set automatically by Piano (organic vs. campaigns).

What is `src_force` used for in Piano Analytics?

The property src_force: true allows you to force the marketing source of a visit even if another source (e.g. UTM link, referrer) has already been detected. This is very useful when you want to make sure that the right campaign is attributed For example, in the case of an e-mail reminder, a specific promotional code, or a well-defined marketing context.

A simple example:

pa.sendEvent("page.display", {
  page: "home",
  src_medium: "email",
  src_campaign: "relance-avril",
  src_force: true // 👈 Force cette source comme origine de la visite
});

💡 Tip: Specify `src_force` only when `at` or `utm` parameters are present in the URL. Please note: only the last forced source of the visit will be retained. And this modification will only apply to reports from the following day. (real-time exports do not take into account the src_force).

Example using Angular (SPA):

var hasSearchParams = window.location.search.includes('at_medium') && window.location.search.includes('at_campaign');
var hasHashParams = window.location.hash.includes('at_medium') && window.location.hash.includes('at_campaign');
    if (hasSearchParams || hasHashParams) {
        window['_paq'].push(["setProperty", "src_force", true, {
            "events": ["page.display"]
        }]);

What about consent?

The parameters of consent (optin, exempt, no-consent) govern what you are allowed to collect or store (cookies, identifiers, etc.). They are managed via:

pa.setConsent("optin"); // ou "exempt", "no-consent"...

Combined use case (consent + marketing source forcing):

// Exécution après clic sur "J'accepte" dans le bandeau cookies
pa.setConsent("optin");

// On renvoie immédiatement un événement marketing, en forçant la campagne
pa.sendEvent("consent.update", {
  src_medium: "email",
  src_campaign: "newsletter-mai",
  src_force: true // On s'assure que cette source remplace toute autre déjà détectée
});

src_force = marketing tool to force a campaign → not linked to consent per se

setConsent() = GDPR tool to declare consent status

💡 But you can combine them Forcing a marketing source after consent, so as not to lose attribution.

8.8 Why "N/A" in reports?

Events in no-consent or opt-out are cleaned with processing. They do not contain any information that can be used individually, which often results in N/A in the interface.

8.9 Use case: cross-referencing exempt and opt-in

You can analyze audience differences between modes with:

visitor_privacy_mode = "exempt" OR "optin"

Or use a custom dimension to display volumes by consent type.

In a nutshell

Exempt mode is a CNIL-compliant solution
It ensures that the audience is not completely lost without consent
But it imposes a strict minimization of data and enhanced governance

8.10 Checklist and best practices

✔️ Make sure that each hit contains the following properties visitor_privacy_mode and visitor_privacy_consent
✔️ Hide visitor IDs in exempt mode
✔️ Activate exempt property buffers only if documented
✔️ Use Stream Inspector to check exempt/optin events

8.11 Additional resources

10. Create and manage dashboards with Boards

Boards is Piano Analytics' native tool for building simple, customizable, platform-integrated internal dashboards. It's a practical alternative to external BI tools such as Looker Studio or Power BI, with specific strengths and limitations.

10.1 Why use Boards?

✅ Quickly create dashboards on existing reports
✅ Native sharing within the organization (no third-party connectors)
🚫 Less flexible than BI tools for advanced customization

10.2 Recommended structure

Create or reuse metrics from the Library
Create reports (via Data Query or templates)
Assembling the dashboard (Board) with tiles

10.3 Creating custom metrics

Exemple : taux de conversion = achats / visiteurs
Librairie > + Nouvelle métrique > Appliquer segments et type (ratio, %)

10.4 Generating reports

Librairie > + Nouveau rapport
→ Sélection des dimensions, dates, filtres et segments
→ Sauvegarde pour usage dans un Board

10.5 Board construction

Librairie > + Nouveau Board
→ Ajouter des tuiles (KPI, graphique, table…)
→ Personnaliser les propriétés, formats, et date range
→ Ajouter une description claire pour les utilisateurs
→ Rendre public pour partage d’équipe

10.6 Case studies

Google Ads dashboard: by campaign, ad group, keywords
E-commerce dashboard: conversion rate, average basket, sales by category
Video dashboard: views, engagement, replay ratio
Board Lead Gen: forms submitted, click-through rates, entry pages

10.7 Benefits & limitations

✅ Benefits

Fast loading
No 10k line quota like Looker
Enriched visualizations: funnel, treemap, prediction, KPIs

🚫 Limits

Limited customization
Restricted interactivity
No fine-grained management of access rights yet

10.8 Announced roadmap

Dedicated workspaces by BU or team
Rights management by Board or segment
Improved ergonomics and new tile types

💡 Tip: use the Pre-segmented data queries to simplify filters on the Board side and avoid interpretation errors.

11. Debugging & checking Piano Analytics hits

Good tracking is, above all, verified tracking. This section shows you the recommended methods for auditing the sending of a hit, detecting errors, and understanding what Piano actually receives from your site.

11.1 Check hits in the Network tab

Open your page in Chrome (or Chromium)
F12 > tab Network > check "Preserve log
Reload page
Search for "xiti", "vtag" or your CNAME
Open request → view URL or Payload (GET or POST)

⚠️ The HTTP code must be 200 - another status indicates a network block or error.

11.2 Reading the contents of a hit (SDK)

pa_event event name (e.g. page.display)
stc= JSON-encoded custom properties
ts: timestamp
idclient Visitor ID (invisible in exempt mode)

11.3 Using the Chrome Tag Inspector extension

Download the official Piano extension: Tag Inspector
Once activated, a Tag Inspector tab is added to your Dev console.
Reload page → view all Piano events in real time
Click on the EVENTS column to view each transmitted property
Export session if necessary

💡 For setups with CNAME, check that the collection domain is properly configured in the extension.

11.4 Viewing server-side hits with Stream Inspector

In Piano Analytics: Configuration > Data Collection Portal > Tools > Stream Inspector
Here you can see all the hits collected by Piano live.
Filter by site, event type, property value

⚠️ This tool displays the raw data before any reprocessing (no marketing source, event grouping, etc.).

11.5 Quick debugging checklist

✅ Hit visible in Network or Tag Inspector
✅ HTTP code = 200
✅ Correct event name (Data Model compliant)
✅ No "undefined", empty or ill-typed properties
✅ Custom properties encoded correctly (check stc=)

11.6 When to use which tool?

Tool	Use cases	Level
Network / Console	Rapid manual debugging, structural validation	Developer
Tag Inspector	Complete session visualization, easy reading	Marketing / Tech
Stream Inspector	Validation of hits received by Piano servers	Admin / Expert