Formation Piano Analytics gratuite – 2026

Piano Analytics : implémentation pas à pas

Vous cherchez une solution d’analytics moderne, fiable et respectueuse des normes européennes de confidentialité ? Piano Analytics est une alternative de plus en plus utilisée par les entreprises qui souhaitent reprendre le contrôle sur leurs données en comparaison à notre légendaire Google Analytics. Piano Analytics est un des outils exempté de consentement par la CNIL ce qui en fait un argument fort dans le cadre d’une collecte de données exhaustive et privacy-first.

Cette formation a été conçue pour vous accompagner dans la mise en place de Piano Analytics, depuis la préparation du projet jusqu’à l’analyse des données collectées. Contrairement aux documentations produit Piano chiantes à lire (et hyper complexes au passage), cette formation propose une approche pratique, opérationnelle et centrée sur les enjeux concrets des projets analytics : structuration du compte, construction du data model, configuration du tracking, gestion des droits, respect du RGPD, TMS et recette technique.

Chaque section de ce guide a été pensée pour répondre aux besoins des professionnels confrontés à une refonte, une migration ou une première implémentation de Piano Analytics.

Ce que vous allez apprendre

• Comment structurer efficacement votre compte Piano Analytics
• Comment organiser vos événements, variables et propriétés
• Comment implémenter Piano Analytics sur un site (classique ou SPA)
• Comment intégrer Piano à votre TMS (TagCommander ou GTM)
• Comment tester, recetter et corriger votre plan de marquage
• Et comment respecter les obligations légales liées au consentement

1. Introduction

Piano Analytics est une solution analytics développée par Piano.io, successeur d’AT Internet (SmartTag). Elle repose sur une architecture moderne et centralisée, où les concepts de data model unifié, privacy par design, flexibilité de l’implémentation et collecte first-party sont centraux.

Contrairement à Google Analytics, Piano sépare explicitement les niveaux d’organisation, de tracking et de gestion des droits, ce qui implique une phase de cadrage rigoureuse en amont. Cette formation vous accompagne pour structurer, implémenter et valider ce socle analytics de manière fiable et scalable.

2. Structurer son compte Piano Analytics

2.1 Choisir une architecture adaptée à votre organisation

La structure du compte est la fondation de toute implémentation Piano Analytics. Une mauvaise architecture entraîne des limitations lourdes sur la collecte, l’analyse, la gouvernance et la scalabilité. Il est donc essentiel de prendre le temps de cadrer votre modèle avant tout déploiement.

Les briques de base

• Organisation : niveau racine, équivalent du “compte” dans GA. Le data model y est défini de manière centralisée.
• Sites de niveau 1 : unité de mesure principale (souvent un domaine ou une application). C’est à ce niveau que les hits sont envoyés et que les cookies sont posés.
• Sites de niveau 2 : subdivisions logiques d’un site (ex : sections, sous-domaines), filtrables dans l’interface mais ne collectent pas indépendamment.
• Groupes de sites : ensembles de sites de niveau 1 regroupés à des fins d’analyse agrégée.
• Sites virtuels : duplications reprocessées de la donnée permettant d’analyser un même périmètre sous des angles alternatifs (équivalent roll-up Matomo / GA).

Étude de cas : multi-domaines ou multi-structures ?

Avant d’attribuer vos sites, posez-vous les questions suivantes :

• Mes domaines sont-ils totalement indépendants (ex : marques différentes) ? → Un site de niveau 1 par domaine.
• Mes sous-domaines doivent-ils être analysés séparément ? → Sites de niveau 2 selon les besoins de déduplication.
• Ai-je besoin d’une vue unifiée pour tous les périmètres ? → Utilisation des groupes de sites.
• Chaque entité a-t-elle ses propres équipes analytics ? → Envisager les délégations (voir ci-dessous).

2.2 Gestion des accès et des rôles utilisateurs

Piano Analytics repose sur une gestion hiérarchisée des droits, qui permet une grande flexibilité mais nécessite une gouvernance stricte pour éviter les dérives.

Les 3 niveaux d’attribution de droits

• Organisation : Accès global à tous les sites. L’administrateur peut gérer tous les utilisateurs.
• Délégation : Unité intermédiaire autonome sur un sous-ensemble de sites (par BU, pays, etc.).
• Groupe : Regroupement d’utilisateurs avec des droits définis par rôle sur un ou plusieurs sites.

👤 Rôles utilisateurs standards

Rôle	Description
Document Reader	Accès en lecture seule aux rapports, exports et à l’In-Page Analytics.
Business User	Inclut tous les droits du Document Reader, avec en plus l’accès à Explorer pour consulter les données de manière interactive.
Analyst	Dispose des droits du Business Analyst, et peut en plus créer des segments, des métriques et des rapports. Accès en lecture au Data Model et à l’API.
Advanced Analyst	Possède les droits de l’Analyst, avec des capacités supplémentaires : configuration du tagging (portail de collecte), gestion des flux de données, et options avancées de personnalisation de la solution.
Data Supervisor	Seul rôle autorisé hors administrateurs à modifier la structure du Data Model (création, édition, suppression de propriétés et événements).
Administrator	Tous les droits bien entendu
Custom	Rôle personnalisé permettant de combiner librement les outils (par exemple : lecture + configuration du tagging).

Bonnes pratiques de gouvernance

• Limiter les Data Supervisors & Administrators au strict minimum.
• Formaliser un processus de création/modification de comptes utilisateurs.
• Documenter les rôles affectés et les sites associés.
• Ne jamais donner l’accès complet à des profils externes (agences, prestataires).

3. Concevoir un Data Model robuste

3.1 Qu’est-ce que le Data Model ?

Le data model (modèle de données) de Piano Analytics est l’ensemble des propriétés (dimensions) et des événements que vous collectez sur l’ensemble de vos sites et les et measurements (options d’enrichissement = import de données). Il est défini au niveau de l’organisation et s’applique donc à tous les sites rattachés. Contrairement à Google Analytics, il s’agit d’un modèle centralisé et unifié.

Le Data Model (hors measurements) est structuré ainsi :

• Propriétés : dimensions personnalisées ou natives (ex. : page, device, type d’utilisateur).
• Événements : actions mesurées (ex. : page.display, click.navigation, transaction.confirmation).

Limites à connaître : vous pouvez créer un nombre illimité d’événements personnalisés, mais le nombre de propriétés personnalisées est limité à 1000 par organisation.

3.2 Préparation du Data Model : cadrage et ateliers

Avant toute création de propriété ou d’événement, une phase de cadrage est indispensable. Elle doit réunir les stakeholders métiers et techniques pour :

• Recenser les KPIs et événements business réellement utiles à mesurer.
• Identifier les doublons et incohérences (ex : mêmes données nommées différemment sur plusieurs sites).
• Aligner la structure du data model avec les cas d’analyse attendus dans Explorer ou Data Query.

Il est recommandé de formaliser un document de référence partagé (Notion, Excel, Airtable, Sheets…) avec :

• Un onglet Propriétés (nom affiché, type, clé technique, catégorie, date de création).
• Un onglet Événements (nom, déclencheur, description, portée, catégories).
• Un mapping éventuel avec les dimensions/events utilisés dans l’outil précédent (ex : GA).

3.3 Création et gestion des propriétés personnalisées

Depuis l’interface Piano (Data Management > Propriétés), vous pouvez créer une nouvelle propriété. Il faudra renseigner :

• Libellé : nom lisible dans l’interface (Explorer, Data Query…)
• Description : très utile pour éviter les doublons ou les mauvaises interprétations
• Type : string, integer, date, boolean, etc.
• Clé technique (property key) : identifiant utilisé dans les tags et API (irréversible une fois validé)
• Catégorie(s) : pour filtrer et organiser dans l’interface

⚠️ Attention : une fois une propriété validée, elle est figée : seule sa description est modifiable. Si une erreur est faite sur la clé ou le type, la seule option est de masquer la propriété (elle reste comptabilisée).

3.4 Création d’événements personnalisés

La création d’un événement est plus souple que celle d’une propriété : vous renseignez directement :

• Nom de l’événement (ex : coucou)
• Description (fonction du déclencheur)
• Portée : site ou hors site (ex : CRM, server-side…)
• Catégories (ecommerce, navigation, utilisateur…)

3.5 Retraitement des données & extraction/concaténation

Piano Analytics permet de modifier, extraire ou nettoyer la donnée après collecte au niveau des propriétés via des règles de “processing”. Cela se fait dans l’interface, au niveau de la configuration de chaque propriété, onglet “Processing” :

• Correction : nettoyer un champ mal formaté ou incohérent.
• Mapping : transformer un code interne en libellé lisible via table de correspondance.
• Suppression : vider une donnée incorrecte.
• Extraction / Concaténation : extraire un paramètre d’URL ou concaténer plusieurs champs.

Imports de données

En complément des données collectées via le SDK, Piano permet d’importer des données (fichiers CSV, SFTP ou API) au niveau de l’organisation. Il s’agit de la fonctionnalité “Measurements” dans Piano Analytics (Data Management > Data Model).

C’est une méthode d’import de données numériques agrégées liées à une période donnée (jour, heure, etc.), permettant de contextualiser les données analytiques, par exemple en croisant les ventes avec la météo ou le nombre d’abonnés sur les réseaux sociaux.

Chaque Measurement est défini par une clé, une ou plusieurs valeurs (ex. température, humidité), et peut être enrichi avec des propriétés (comme la région ou le type d’appareil). Les données peuvent provenir d’APIs externes (comme Google Search Console), de fichiers CSV, ou d’outils tiers (comme Adverity), puis être envoyées via l’API dédiée de Piano. Une fois créés, les Measurements permettent de générer des métriques exploitables dans les interfaces comme Explorer ou Workspaces.

La granularité, la portée (site ou organisation), et l’agrégation temporelle doivent être bien définies. Les données sont visibles rapidement, sauf en cas de cache, et peuvent être corrigées simplement. Certaines propriétés fines (ex. event_time, visitor_id) sont interdites.

🧠 Bonnes pratiques globales

• Préfixez les noms de vos événements et propriétés (ex : ecom.product_id, ux.page_type).
• Avoir une convention de nommage pour les propriétés (ex : préfixer le nom par métier)
• Masquez les propriétés obsolètes pour garder un modèle clair.

4. Implémentation technique de Piano Analytics

4.1 Chargement de la librairie Piano Analytics

La première étape de l’intégration consiste à charger la librairie JS de Piano Analytics sur votre site. Trois méthodes sont disponibles :

• Librairie CDN (dernière version) : https://tag.aticdn.net/piano-analytics.js
• Librairie CDN versionnée : https://tag.aticdn.net/js-sdk/piano-analytics-<version.number>.js
• Librairie auto-hébergée : à récupérer sur le GitHub Piano

Vous pouvez trouver une liste de toutes les versions du SDK JS disponibles sur la page des versions de Github https://github.com/at-internet/piano-analytics-js/releases

Une fois la librairie chargée, deux méthodes de configuration existent :

Méthode basique (synchrone)

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

Méthode SDK (asynchrone)

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

Conseil : placez le chargement de la librairie dans le <head> de vos pages, avec vos configurations principales (site, domaine, privacy…)

4.2 Méthodes de tagging

Piano Analytics offre deux manières d’envoyer des événements :

Méthode directe

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

Méthode asynchrone (queue)

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

La méthode à utiliser dépend de votre stack technique et TMS. En général, la méthode par queue est recommandée pour les intégrations via Tag Manager mais elle est encore peu répandue, la majorité des utilisateurs continuant d’utiliser des pa.sendEvent comme historiquement. Ma préférence personnelle ? Aucune, les deux semblent être assez similaires si vous n’avez pas besoin de la logique de queue.

4.3 Ajouter des propriétés globales

Vous pouvez définir des propriétés valables sur tous les événements suivant leur définition :

Propriété unique

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

Plusieurs propriétés en bloc

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

La persistance permet d’injecter ces propriétés automatiquement dans les prochains événements envoyés, sans les répéter.

4.4 Bonnes pratiques de tagging

• Respecter strictement le type des propriétés déclarées dans le Data Model (ex. : integer, string)
• Utiliser des préfixes clairs pour vos événements personnalisés (ex : form.submit, product.add)
• Vérifier les hits dans la console réseau : filtrez sur xiti ou event
• Ne pas utiliser la concaténation de chapitres (::) comme dans SmartTag. Piano demande des champs séparés.
• Typage obligatoire : certaines données doivent être des chaînes (ex. : si une propriété utilise une table de correspondance, elle doit être en string)

Erreur fréquente : envoyer un transaction.id en nombre entier (integer) alors qu’il est défini en string dans le modèle bloque l’analyse des transactions !

4.5 Envoyer des événements avec Piano Analytics SDK

Piano Analytics repose sur une architecture event-based. Cela signifie que chaque action à mesurer (page vue, clic, interaction, conversion…) doit être envoyée via un événement nommé, avec des propriétés associées.

Deux méthodes principales existent :

• pa.sendEvent(name, properties) : pour un seul événement
• pa.sendEvents([{ name, data }, ...]) : pour plusieurs événements en même temps

`pa.sendEvent()` — envoyer un seul événement

C’est la méthode la plus utilisée. Elle s’utilise dans 90% des cas : page vue, clic, impression, conversion…

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

⚠️ Le nom de l’événement ("page.display" ici) doit correspondre à un événement défini dans votre Data Model. Il peut être natif ou personnalisé.

`pa.sendEvents()` — envoyer plusieurs événements d’un coup

Utile lorsqu’on souhaite déclencher plusieurs événements simultanément, par exemple à la confirmation d’un achat (commande + produits achetés).

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

Chaque objet envoyé via pa.sendEvents doit contenir deux clés :

• name : le nom de l’événement
• data : les propriétés associées

💡 Recommandations

• Utilisez pa.sendEvent pour les cas simples et immédiats
• Privilégiez pa.sendEvents dans des scénarios e-commerce ou transactionnels complexes
• Évitez de dépasser 20 événements simultanés dans une seule requête
• Respectez le typage de chaque propriété (ex : string vs integer)
• Définissez des propriétés persistantes en amont si certaines données doivent être présentes sur plusieurs événements

Tous les événements envoyés peuvent être visualisés via le Stream Inspector de Piano Analytics, pour vérifier leur bon envoi et leur structuration.

📄 Page vue

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

🖱 Clic (action, navigation…)

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

🛒 Transaction e-commerce

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. Intégrer Piano Analytics via un TMS

L’intégration via un TMS permet de déployer Piano Analytics de manière modulaire, sans modifier directement le code source du site. Elle facilite la maintenance, la recette, la gouvernance et les évolutions futures.

5.1 Implémentation avec Tag Commander

Étapes recommandées

• Balise INIT : chargement de la librairie + configuration globale
• Balise page display : événement de base de toutes les pages
• Balise événements : clics, scroll, interaction (diviser si nomenclature complexe)
• Balise e-commerce : actions liées au tunnel de conversion
• Balise privacy : consentement, optin/optout (si pas géré ailleurs)

Méthode recommandée : balise Free Input

Évitez les templates limités : préférez les balises “Free Input” avec votre propre script Piano.

Exemple de configuration INIT (asynchrone) – plus de détails ci-dessus

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

Exemple de balise événement

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

Une fois vos balises créées :

• Testez-les dans le navigateur (onglet Network, filtre xiti, ou filtre pa-cd si nouveau domaine de collecte)
• Déployez une version dédiée à la recette
• Recettez avec Tag Inspector ou en overridant le javascript du conteneur.

5.2 Implémentation avec Google Tag Manager (GTM)

GTM est l’outil de taggage le plus utilisé dans les écosystèmes digitaux. L’implémentation de Piano s’y fait via :

• Balise HTML personnalisée (script complet)
• Template communautaire (galerie GTM)

Exemple balise HTML personnalisée

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

Template officiel Piano Analytics

Importez via la galerie communautaire. Deux éléments sont nécessaires :

• Une variable de configuration (site ID, domaine, privacy mode…)
• Une ou plusieurs balises d’action (send event, set privacy…)

💡 Astuce : Séquençage

La balise de configuration (init) doit être exécutée avant toute balise événement (via la fonction de séquençage GTM).

5.3 Tracking Server-Side avec CommandersAct X

CommandersAct X permet de configurer une collecte server-side vers Piano Analytics, via la Collection API. Cela réduit la dépendance au navigateur (cookies, adblock, JS).

Prérequis

• Implémentation CommandersAct côté client (browser)
• Création d’une destination Piano dans la console CommandersAct
• Configuration du mapping entre événements CommandersAct (ex: purchase) et Piano (transaction.confirmation)

Particularités

• Ajouter le paramètre visitor_privacy_mode dans les événements pour gérer le consentement
• Configurer deux destinations si vous utilisez la mesure hybride : user_consent = Piano et user_consent = Fonctionnement

Recette

Utilisez le Event Inspector intégré à CommandersAct pour visualiser les hits vers Piano. Vérifiez que :

• Le site ID et domaine de collecte sont bien présents
• Les événements ont les bons noms et bonnes propriétés
• Les données s’affichent bien dans Stream Inspector et Data Query

Remarque : le full server-side sans client (JS) ne permet pas de compter les visites (absence de cookies Piano) → utilisez-le en hybride.

6. Recette & validation du tracking

Une implémentation Piano Analytics n’est fiable que si elle a été recettée rigoureusement. Cette phase permet de s’assurer que :

• La solution est correctement initialisée
• Les événements sont envoyés selon les règles définies
• Les propriétés attendues sont bien transmises et valorisées
• Les contraintes de privacy (consentement) sont respectées

6.1 Préparer la recette

Créer une checklist de validation

Avant de tester, créez un document de suivi listant :

• Les pages et parcours clés à tester
• Les événements attendus (nom exact, conditions de déclenchement)
• Les propriétés attendues pour chaque event
• Le respect des modes de consentement (opt-in, exempté, refus)

Astuce : utilisez des outils comme Google Sheets, Notion ou Airtable pour tracer vos tests par environnement (DEV, PREPROD, PROD).

6.2 Outils de validation technique

Console du navigateur

• Ouvrez les outils de dev (F12 ou clic droit > Inspecter)
• Allez dans l’onglet Network
• Filtrez sur xiti , pa-cd ou event?
• Inspectez les paramètres dans le sous-onglet Payload

Extension Chrome : Piano Tag Inspector

Affiche tous les hits Piano (page views, clics…), avec les propriétés et types d’événements.

• Utilisable en complément du Network
• Affichage plus lisible, utile pour les profils non techniques

Google Tag Manager : Mode prévisualisation

• Permet de vérifier que les balises Piano Analytics sont bien déclenchées
• Inspectez les balises via la rubrique Tag Details
• Validez que les bonnes variables sont injectées au bon moment

Interface Piano Analytics

• Stream Inspector : visualisation en temps réel des événements reçus
• Data Query : exploration du data model (propriétés, formats, valeurs)

Attention : les règles de processing ne sont appliquées qu’après collecte → elles ne s’affichent pas dans les outils de debug front.

7. Bonnes pratiques globales

7.1 Structuration et gouvernance

• Cadrer l’architecture dès le départ : chaque mauvaise décision initiale (site unique trop large, data model mal pensé) impactera durablement vos analyses.
• Séparer PROD et PREPROD : créez des sites distincts pour les tests et évitez toute pollution de données.
• Limiter les accès critiques : seuls les administrateurs et Data Supervisors doivent pouvoir créer ou modifier le data model.
• Formaliser un process de création de propriété : valider les besoins métiers, le typage, la clé technique, les catégories avant d’enregistrer.
• Adopter une convention de nommage claire : uniformisez les noms d’événements, de propriétés, de sites (ex : product.add_to_cart, form.submit_contact).

7.2 Documentation & collaboration

• Tenir à jour un fichier centralisé du data model : type, propriété, valeur, date de mise en prod, lien vers tag…
• Tracer tous les ajouts/retours : versionnez votre fichier modèle avec des dates et des validations
• Documenter les règles de processing : tout retraitement (cleaning, mapping, enrichissement) doit être visible et commenté
• Partager les accès intelligemment : évitez les comptes génériques ou “super admin” en masse, préférez les groupes ciblés

7.3 Implémentation & maintenance

• Définir un plan de marquage clair : parcours, déclencheurs, priorités
• Recetter chaque balise avant mise en prod : utilisez Piano Tag Inspector, la console ou les outils internes Piano
• Respecter les typages : le moindre décalage string/integer bloque le traitement
• Centraliser les erreurs de tracking : utilisez une feuille d’erreurs et une logique de ticketing si besoin
• Suivre un changelog : tout changement dans le marquage ou le data model doit être documenté

7.4 Scalabilité & pérennité

• Utiliser les sites virtuels avec parcimonie : attention aux coûts et à la double collecte
• Planifier des revues trimestrielles : vérification du data model, des propriétés obsolètes, des règles de processing
• Adopter une approche modulaire : découpez votre implémentation par balises/fonctionnalités pour faciliter les évolutions
• Former régulièrement vos équipes : chefs de projet, analystes et techs doivent comprendre le fonctionnement du modèle Piano

En résumé : une implémentation réussie repose autant sur une technique bien maîtrisée que sur une gouvernance solide et une documentation continue. Ce guide vous fournit les clés pour structurer durablement votre dispositif Piano Analytics.

8. Privacy & Mesure Hybride (Exemption CNIL)

8.1 Comprendre les statuts de consentement

• Opt-in : consentement explicite de l’utilisateur → collecte complète autorisée
• Exempt : absence de choix explicite (abstention ou refus 1er/2e niveau via CMP) → collecte partielle possible
• Opt-out : refus explicite (souvent 3e niveau via bouton de gestion) → aucune donnée personnelle collectée

8.2 Scénarios dans la mesure hybride

• Acceptation (opt-in) : tous les cookies sont posés, collecte complète activée
• Abstention (exempt) : collecte limitée aux données nécessaires, sans cookies marketing
• Refus (opt-out) : aucun cookie ni information nominative n’est collecté

Pour utiliser légalement le mode exempté en France dans le cadre de l’Exemption CNIL, il est impératif de suivre les recommandations du guide de la CNIL :

• Signer l’annexe contractuelle DPA ePrivacy avec AT Internet
• Faire une demande d’activation via votre Customer Success Manager (CSM)
• Appliquer toutes les restrictions de marquage définies par Piano Analytics (voir ci-dessous)
• Recevoir une attestation de conformité fournie par Piano après validation

Privacy Modes dans Piano Analytics

Depuis la version 6.8 du SDK JavaScript, Piano Analytics introduit un module unifié : Consent Management.

Chaque visiteur est associé à un visitor_privacy_mode et un visitor_privacy_consent pour contrôler dynamiquement la collecte des données.

Mode	Cookie	ID Visiteur	Consentement	Données collectées	Anonymisation
optin	✅	GUID	true	toutes	❌
exempt	✅	❌	false	partielles	✅
no-consent	❌	❌	false	limitées	✅
optout	✅	❌	false	limitées	✅
custom	personnalisé	personnalisé	variable	à configurer	variable

8.3 Implémentation du consentement dans le marquage

Avant tout envoi d’événement, vous devez définir le mode de privacy avec :

// 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");
}

Gestion du mode via SDK

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

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

Inclusion/Exclusion fine

Inclure des identifiants si exempt :

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

Autres exemples :

// 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"]);

Inclure des propriétés selon le mode de privacy :

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

Inclure des événements selon le mode de privacy :

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

Exclure des événements selon le mode de privacy :

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

Créer un Privacy Mode personnalisé

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

Cela permet d’adapter entièrement le comportement du SDK à votre politique de consentement.

8.4 Buffer en mode exempt : minimiser la donnée collectée

En mode exempt, seules les propriétés strictement nécessaires doivent être collectées. Ajoutez-les explicitement :

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

Bonnes pratiques : éviter toute propriété marketing ou identifiante (ex : user_id, campaign, revenue…)

8.5 Propriétés automatiques par mode

• visitor_privacy_mode → indique le mode de l’utilisateur (optin / exempt / optout)
• visitor_privacy_consent → booléen (true si optin)

Ces propriétés peuvent être utilisées dans Data Query ou les dashboards pour filtrer le trafic selon le statut de consentement.

8.6 Restrictions du mode exempté

• Pas de données nominatives, identifiants, user_id
• Pas d’exports non agrégés
• Pas d’utilisation de données importées (ex : CRM)
• Pas de recoupements entre visites → uniquement des cohortes
• Traceurs limités à 13 mois, IP anonymisée (dernier octet masqué)

⚠️ À noter : seules les données agrégées anonymisées sont conservées. Le module d’attribution n’est donc que partiellement alimenté en mode exempt.

8.7 Sources marketing et exempt

• Les sources naturelles sont conservées (referrer, search)
• Les campagnes marquées avec xtor ne sont pas interprétées → utiliser at_*
• Le type source est défini automatiquement par Piano (organic vs campaigns)

À quoi sert src_force dans Piano Analytics ?

La propriété src_force: true permet de forcer la source marketing d’une visite, même si une autre source (ex : lien UTM, referrer) a déjà été détectée auparavant. C’est très utile dans les cas où tu veux t’assurer que la bonne campagne soit attribuée, par exemple lors d’une relance e-mail, d’un code promo spécifique, ou d’un contexte marketing bien défini.

Exemple simple :

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

💡 Conseil : préciser le src_force uniquement quand paramètres at ou utm présents dans l’url. Attention : seule la dernière source forcée de la visite sera retenue. Et cette modification ne s’appliquera dans les rapports qu’à partir du lendemain (les exports temps réel ne prennent pas en compte le src_force).

Exemple sur 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"]
        }]);

---

Et le consentement dans tout ça ?

Les paramètres de consentement (optin, exempt, no-consent) régissent ce que tu as le droit de collecter ou de stocker (cookies, identifiants, etc.). Ils sont gérés via :

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

---

Cas d’usage combiné (consentement + forçage source marketing) :

// 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 = outil marketing pour forcer une campagne → pas lié au consentement en soi

setConsent() = outil RGPD pour déclarer le statut de consentement

💡 Mais tu peux les combiner : forcer une source marketing après le consentement, pour ne pas perdre l’attribution.

8.8 Pourquoi des “N/A” dans les rapports ?

Les événements en mode no-consent ou opt-out sont nettoyés au processing. Ils ne comportent aucune information exploitable individuellement, ce qui se traduit souvent par des N/A dans l’interface.

8.9 Cas d’usage : croiser exempt et opt-in

Vous pouvez analyser les écarts d’audience entre modes avec :

visitor_privacy_mode = "exempt" OR "optin"

Ou via une dimension personnalisée si besoin pour afficher les volumes par type de consentement.

En résumé

• Le mode exempté est une solution conforme à la CNIL
• Il permet de ne pas perdre totalement l’audience sans consentement
• Mais il impose une minimisation stricte des données et une gouvernance renforcée

8.10 Checklist et bonnes pratiques

• ✔️ Assurez-vous que chaque hit contient les propriétés visitor_privacy_mode et visitor_privacy_consent
• ✔️ Masquez les ID visiteurs en mode exempt
• ✔️ Activez les buffers de propriétés exemptées uniquement si documentées
• ✔️ Utilisez Stream Inspector pour vérifier les événements exempt/optin

8.11 Ressources complémentaires

• Privacy Center
• Règles des modes Privacy
• Cookies & Storage

10. Créer et exploiter des tableaux de bord avec Boards

Boards est l’outil natif de Piano Analytics pour construire des tableaux de bord internes simples, personnalisables, et intégrés à la plateforme. C’est une alternative pratique aux outils BI externes comme Looker Studio ou Power BI, avec des atouts et limites spécifiques.

10.1 Pourquoi utiliser Boards ?

• ✅ Création rapide de dashboards sur des rapports existants
• ✅ Partage natif au sein de l’organisation (pas de connecteur tiers)
• 🚫 Moins flexible que les outils BI pour les personnalisations poussées

10.2 Structure recommandée

1. Créer ou réutiliser des métriques depuis la Librairie
2. Créer des rapports (via Data Query ou templates)
3. Assembler le tableau de bord (Board) avec des tuiles

10.3 Créer des métriques personnalisées

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

10.4 Générer des rapports

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

10.5 Construction du Board

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 Cas pratiques

• Board Google Ads : par campagne, groupe d’annonces, mots-clés
• Board E-commerce : taux de conversion, panier moyen, ventes par catégorie
• Board Vidéo : vues, engagement, ratio replay
• Board Lead Gen : formulaires soumis, taux de clics, pages d’entrée

10.7 Avantages & limitations

✅ Avantages

• Chargement rapide
• Pas de quota 10k lignes comme Looker
• Visualisations enrichies : funnel, treemap, prédiction, KPI

🚫 Limites

• Personnalisation limitée
• Interactivité restreinte
• Pas encore de gestion fine des droits d’accès

10.8 Feuille de route annoncée

• Workspaces dédiés par BU ou équipe
• Gestion des droits par Board ou segment
• Meilleure ergonomie et nouveaux types de tuiles

💡 Astuce : utilisez les Data Queries pré-segmentées pour simplifier les filtres côté Board et éviter les erreurs d’interprétation.

11. Debug & Vérification des hits Piano Analytics

Un bon tracking, c’est avant tout un tracking vérifié. Cette section vous présente les méthodes recommandées pour auditer l’envoi d’un hit, détecter les erreurs, et comprendre ce que Piano reçoit réellement depuis votre site.

11.1 Vérifier les hits dans l’onglet Réseau (Network)

1. Ouvrez votre page dans Chrome (ou Chromium)
2. F12 > onglet Network > cochez “Preserve log”
3. Rechargez la page
4. Cherchez “xiti”, “vtag” ou votre CNAME
5. Ouvrez la requête → consultez l’URL ou le Payload (GET ou POST)

⚠️ Le code HTTP doit être 200 — un autre statut indique un blocage ou une erreur réseau.

11.2 Lire le contenu d’un hit (SDK)

• pa_event : nom de l’événement (ex: page.display)
• stc= : JSON encodé des propriétés personnalisées
• ts : timestamp
• idclient : identifiant visiteur (invisible en exempt)

11.3 Utiliser l’extension Chrome Tag Inspector

• Téléchargez l’extension officielle Piano : Tag Inspector
• Une fois activée, un onglet Tag Inspector s’ajoute à votre console Dev
• Rechargez la page → visualisez tous les events Piano en temps réel
• Cliquez sur la colonne EVENTS pour voir chaque propriété transmise
• Exportez la session si besoin

💡 Pour les setups avec CNAME, vérifiez que le domaine de collecte est bien configuré dans l’extension.

11.4 Visualiser les hits côté serveurs avec Stream Inspector

1. Dans Piano Analytics : Configuration > Data Collection Portal > Outils > Stream Inspector
2. Vous y verrez tous les hits collectés par Piano en live
3. Possibilité de filtrer par site, type d’événement, valeur de propriété

⚠️ Cet outil affiche la donnée brute avant tout retraitement (pas de source marketing, de regroupement d’événements, etc.).

11.5 Checklist de debug rapide

• ✅ Hit visible dans Network ou Tag Inspector
• ✅ Code HTTP = 200
• ✅ Nom d’événement correct (conforme au Data Model)
• ✅ Aucune propriété “undefined”, vide ou mal typée
• ✅ Propriétés personnalisées bien encodées (vérifier stc=)

11.6 Quand utiliser quel outil ?

Outil	Cas d’usage	Niveau
Network / Console	Debug rapide à la main, validation structurelle	Développeur
Tag Inspector	Visualisation session complète, lecture facilitée	Marketing / Tech
Stream Inspector	Validation des hits reçus côté serveurs Piano	Admin / Expert