Catalogs
Présentation
Catalogs permet de connecter automatiquement vos catalogues métier (produits, contenus, services, clients…) à vos données comportementales dans Piano Analytics. Fini les analyses limitées à des identifiants techniques : vos rapports prennent tout leur sens métier, sans complexité d’implémentation.
Catalogs est l'évolution d’une fonctionnalité historique de Piano Analytics : Enrichments. Pour les clients qui avaient déjà configuré des enrichissements, ces derniers ont été migré automatiquement en catalogues.
Pourquoi Catalogs ?
Chaque organisation possède des catalogues métier structurés (produits, contenus, clients…). Ces catalogues sont essentiels pour comprendre comment vos utilisateurs interagissent avec ce qui compte vraiment pour vous.
Avec Catalogs :
Vous collectez uniquement des identifiants (ex : product_id)
Piano Analytics enrichit automatiquement chaque événement avec toutes les informations pertinentes de votre catalogue, côté serveur et en toute sécurité.
Fonctionnement général
Un catalogue dans Piano Analytics se compose de :
Une clé de réconciliation (ex : product_id) : identifiant commun entre vos événements et votre catalogue métier.
Des propriétés enrichies : informations métier ajoutées automatiquement à vos événements (ex : nom du produit, catégorie).
Schéma de fonctionnement

Les deux contextes : Snapshot et Update
Lors de la création d’un catalogue, vous choisissez un contexte qui détermine comment les données du catalogue sont appliquées à vos événements.
1. Contexte « Snapshot » (Instantané)
Capture l’état du catalogue au moment exact de l’événement.
L’information est figée dans le temps.
Exemple :
Un produit coûte 100 € le 1er janvier. Même si le prix change à 120 € plus tard, l’événement du 1er janvier affichera toujours 100 €.
À privilégier pour :
Analyses historiques précises
Conformité réglementaire
Tests A/B
2. Contexte « Update » (Mis à jour)
Applique la version la plus récente du catalogue à tous les événements, même passés.
Exemple :
Si le prix d’un produit passe de 100 € à 120 €, tous les événements afficheront désormais le prix actuel de 120 €.
À privilégier pour :
Analyses ou personnalisations basées sur l’état actuel du catalogue
Mise à jour continue des analyses
Le contexte Update est une option payante.
Si vous souhaitez l’activer, contactez votre responsable de compte Piano Analytics pour plus d’informations sur la tarification et l’activation.
Création et gestion d’un catalogue
Accès
Menu Data Management > Catalogs
Étapes principales
Choisir le type de catalogue
Standard : template prêt à l’emploi recommandé par Piano (clé et propriétés pré-définies)
Personnalisé : configurez votre propre clé de réconciliation et vos propriétés enrichies

Renseigner les informations principales
Libellé d’affichage : nom du catalogue dans l’interface
Contexte : snapshot ou update (voir plus haut)
Clé de réconciliation : propriété existante dans votre data model, alimentée dans votre marquage
Sensibilité à la casse : matching case-sensitive ou non
Data Feed Type : méthode d’import de votre catalogue métier (API, sFTP, ou import manuel CSV via l’interface).
Ce choix détermine comment vous importerez vos données (voir section Import pour plus de détails).Alerte : notification par mail en cas d’échec d’import (pour les imports CSV)

Définir la structure du catalogue
Clé de réconciliation (ex : product_id)
Propriétés enrichies (ex : nom, catégorie, prix…)

Astuce : Pour un contexte Snapshot, les propriétés enrichies doivent déjà exister dans votre data model. Pour Update, vous pouvez les créer lors de la configuration.
Pour les détails avancés (gestion des propriétés, limites, validations, voir l’annexe en fin de doc).
Import de données
Trois modes d’import sont disponibles :
Mode d’import | Format | Limite de taille | Particularités |
---|---|---|---|
API | JSON, ndJSON | 100 Ko ligne, 1 Go body | Import programmatique, endpoints fournis |
sFTP | CSV | 5 Go (1 Go recommandé) | Serveur dédié à demander au support |
Import manuel (UI) | CSV | 10 Mo | Drag & drop ou sélection via interface |
L’interface vous guide sur le format attendu et propose un exemple adapté à votre structure.
Vérification automatique des fichiers importés (présence des colonnes, erreurs de format…).
Pour les formats exacts, exemples de fichiers, gestion des erreurs, reportez-vous à l’annexe.
Monitoring et alertes
Rapport de processing : visualisez les dernières erreurs d’import (par mode d’import).

Aperçu : consultez les 10 dernières lignes importées et filtrez sur une clé spécifique.
Cas d’usage
Cas d’usage Snapshot
1. Analyse des ventes par collection (e-commerce)
Problème : Vous souhaitez mesurer la performance de chaque collection à un instant donné, y compris lors de changements de prix ou de gamme.
Solution :
Collectez uniquement le
product_id
lors des achats.Utilisez un catalogue en contexte Snapshot avec les propriétés
Nom du produit
,Collection
,Prix
.Les rapports historiques reflèteront toujours les valeurs (ex : prix) au moment de l’achat.
2. Suivi de l’engagement sur une offre à durée limitée (média)
Problème : Vous lancez une offre spéciale sur certains contenus et souhaitez garder la trace de l’état de l’offre lors de chaque interaction.
Solution :
Collectez le
content_id
lors de chaque vue.Utilisez un catalogue Snapshot avec les propriétés
Nom du contenu
,Type d’offre
.Analysez l’impact de l’offre, même après modifications ou expiration.
Cas d’usage Update
1. Personnalisation dynamique de l’expérience utilisateur (e-commerce)
Problème : Vous souhaitez que toutes les analyses reflètent la dernière version de votre catalogue (ex : disponibilité, prix, catégorie).
Solution :
Collectez
product_id
à chaque interaction.Utilisez un catalogue Update avec les propriétés
Prix
,Disponibilité
.Toutes les analyses et segments utilisent l’état actuel du catalogue, même pour les événements passés.
2. Mise à jour continue des catégories éditoriales (média)
Problème : Les rubriques de vos contenus changent régulièrement et vous souhaitez que vos analyses soient toujours à jour.
Solution :
Collectez
content_id
à chaque consultation.Utilisez un catalogue Update avec la propriété
Rubrique
.Les dashboards reflètent toujours la rubrique actuelle, même pour les articles anciens.
Autres cas d'utilisation
Pour le E-commerce/Retailers : Noms des produits, catégories, marques, couleurs, tailles, prix, informations sur les marges, niveaux de stock.
Pour les Médias/Edition : Titres d'articles, noms d'auteurs, dates de publication, catégories de contenu, types d'abonnements, statut des paywalls.
Pour les Services Financiers : Types de comptes, noms des produits d'investissement, profils de risque, niveaux de service.
Pour le Voyage/Hôtellerie : Noms des établissements, types de chambres, destinations, listes des services.
FAQ
Q : Je souhaite utiliser un catalogue standard, mais il est grisé. Pourquoi ?
R : Le template est déjà utilisé sur l’organisation ou la clé de réconciliation n’est pas validée. Consultez la liste des propriétés dans Data Management.
Q : Pourquoi une propriété n’apparaît pas lors de la création d’un catalogue Snapshot ?
R : Seules les propriétés “processée” et non de type array/object sont disponibles.
Q : Que se passe-t-il si une propriété enrichie est aussi présente dans mon marquage ?
R :
Snapshot : Si la clé de réconciliation n’existe pas, la valeur du marquage est conservée. Si elle existe, la valeur du catalogue écrase celle du marquage.
Update : La propriété du marquage n’est jamais prise en compte.
Q : Qui peut utiliser le contexte Update ?
R : Le contexte Update est une option payante. Contactez votre responsable de compte pour plus d’informations.
Glossaire
Terme | Définition |
---|---|
Clé de réconciliation | Identifiant commun entre vos événements et votre catalogue métier (ex : product_id) |
Propriété enrichie | Information métier ajoutée automatiquement à vos événements (ex : nom, catégorie, prix) |
Contexte Snapshot | Mode où l’état du catalogue est figé au moment de l’événement |
Contexte Update | Mode où l’état le plus récent du catalogue est appliqué à tous les événements |
Data Feed Type | Méthode d’import de votre catalogue (API, sFTP, CSV manuel) |
Catalogue standard | Template de catalogue proposé par Piano Analytics, prêt à l’emploi |
Catalogue personnalisé | Catalogue configuré sur mesure, avec vos propres propriétés et clé de réconciliation |
Détails avancés (Annexe)
Création et gestion – Détails
Standard vs Personnalisé
Standard : templates proposés par Piano avec clé et propriétés non modifiables, contexte fixe.
Personnalisé : choix libre de la clé de réconciliation (attention à la limite de 2 millions de valeurs uniques/jour), propriétés enrichies personnalisables.
Libellé d’affichage
Personnalisable pour les catalogues personnalisés, imposé pour les standards.
Clé de réconciliation
Doit exister dans votre data model et être alimentée dans le marquage.
Sensibilité à la casse : définit si le matching entre marquage et catalogue est case-sensitive (non modifiable après création).
Propriétés enrichies
Snapshot : doivent être déclarées au préalable dans le data model, de type simple (ni array, ni object), et “processée”.
Update : peuvent être créées lors de la configuration du catalogue, accessibles ensuite dans l’onglet “Propriétés” de Data Management.
Data Feed Type
API : import programmatique via endpoints Piano.
sFTP : import automatisé via dépôt de fichiers CSV sur serveur dédié.
Import manuel (UI) : glisser-déposer ou sélection de fichier CSV directement dans l’interface.
Alerte
Système de notification par mail configurable pour les imports CSV (drag & drop ou sFTP).
Import – Détails
API
Import possible ligne à ligne (JSON) ou groupé (ndJSON).
Limites : 100 Ko/ligne, 1 Go total pour ndJSON.
Authentification par token, endpoint et exemple de payload fournis dans l’interface.
La documentation développeur est disponible ici.
sFTP
Serveur dédié créé sur demande via le support Piano Analytics.
Fichiers CSV, max 5 Go (1 Go recommandé pour performance).
Respect du schéma défini lors de la création du catalogue.
Import manuel (UI)
Fichier CSV, max 10 Mo.
Schéma téléchargeable ou copiable depuis l’interface.
Vérification automatique : présence de la clé de réconciliation, cohérence des propriétés, aperçu des 10 premières lignes.
Notifications en cas d’erreur ou de colonnes manquantes.
Gestion des erreurs
Rapport de processing disponible pour chaque import, différencié selon le mode d’import.
Alerte mail en cas d’échec (si configurée).
Limitations et conseils
Limite de 2 millions de valeurs uniques par jour sur la clé de réconciliation : au-delà, le catalogue est mis en pause.
Propriétés enrichies : une propriété ne peut être enrichie que dans un seul catalogue à la fois.
Modification : la clé de réconciliation et le contexte ne sont plus modifiables après création du catalogue.
Disponibilité :
Contextes Snapshot : inclus sans surcoût.
Contextes Update : option payante, se rapprocher de votre responsable de compte.
Pour toute question, consultez la FAQ ou contactez votre support Piano Analytics si besoin.