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

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

2. 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)

3. 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 :

• 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

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.

  • Est de type String ou Integer.

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

  • Doivent partager la même portée que la clé de réconciliation.

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