Comment implémenter le SDK Piano Analytics ?

Ce guide décrit la mise en place du SDK JavaScript Piano Analytics sur un nouveau site.

Prérequis

Vous devez avoir préalablement créé votre site dans Data Collection Portal et récupéré votre site_id ainsi que le domaine de collecte (voir Comment ajouter un nouveau site dans Piano Analytics ?)

Étape 1 — Charger le SDK

Ajoutez le script du SDK dans votre page, idéalement dans le <head> :

<script src="https://tag.aticdn.net/piano-analytics.js"></script>

Étape 2 — Configurer

Appelez pa.setConfigurations() avec votre site ID et votre domaine de collecte (tous deux obligatoires) :

CODE

pa.setConfigurations({
  site: 123456,
  collectDomain: "votre-domaine-de-collecte.com"
});

Référence complète de la configuration : https://developers.piano.io/analytics/data-collection/how-to-send-events/send-events-via-sdks/

Étape 3 — Envoyer des événements

CODE

pa.sendEvent('page.display', {
  'page': 'homepage',
  'page_chapter1': 'main'
});

L'ordre de chargement est important : le SDK doit être chargé et configuré avant tout appel de tracking. Si pa.sendEvent() s'exécute avant pa.setConfigurations(), les événements ne seront pas collectés.

Délai d'apparition des données

Les tags se déclenchent immédiatement après l'implémentation. Les rapports se remplissent le lendemain (ex. : marquage en ligne le 24 décembre → premières métriques le 25 décembre). Les données ne sont pas rétroactives.

Dépannage

Aucune donnée collectée : vérifiez que le script du SDK se charge avant pa.setConfigurations(). Confirmez que site correspond bien à votre site ID à 6 chiffres et que collectDomain est correct. Vérifiez qu'aucun pare-feu ou bloqueur de publicité n'empêche les requêtes vers le domaine de collecte. Si vous utilisez un TMS, vérifiez l'ordre d'exécution des tags.
Données rattachées au mauvais site : récupérez le bon site ID depuis le Portail de Collecte et comparez-le à la valeur dans votre configuration.
Requêtes en échec ou bloquées : vérifiez le collectDomain, contrôlez les éventuels problèmes de cross-origin et confirmez qu'aucune Content Security Policy ne bloque le domaine de collecte.
Aucune donnée après 24 heures : utilisez les outils de développement du navigateur pour vérifier que le SDK se charge et que les requêtes retournent un HTTP 200. Contactez le Support Piano avec le nom de votre organisation, votre site ID et la version du SDK.