Catalogs

Overview

Catalogs allows you to automatically connect your business catalogs (products, content, services, clients, etc.) to your behavioral data in Piano Analytics. No more analysis limited to technical IDs: your reports gain full business meaning, with no implementation complexity.

Catalogs is the evolution of a historical Piano Analytics feature: Enrichments. For clients who had already configured enrichments, these were automatically migrated to catalogs.

Why Catalogs?

Every organization has structured business catalogs (products, content, clients, etc.). These catalogs are key to understanding how your users interact with what really matters to you.

With Catalogs:

• You only collect identifiers (e.g., product_id)

• Piano Analytics automatically enriches each event with all relevant catalog information, securely and server-side.

How it Works

A catalog in Piano Analytics consists of:

• A reconciliation key (e.g., product_id): a common identifier between your events and your business catalog.

• Enriched properties: business information automatically added to your events (e.g., product name, category).

Workflow Diagram

The Two Contexts: Snapshot and Update

When creating a catalog, you choose a context that determines how catalog data is applied to your events.

1. “Snapshot” Context

• Captures the state of the catalog at the exact moment the event occurs.

• The information is frozen in time.

Example:
A product costs €100 on January 1st. Even if the price later changes to €120, the event from January 1st will always show €100.

Best for:

• Accurate historical reporting

• Regulatory compliance

• A/B testing

2. “Update” Context

• Applies the most recent version of the catalog to all events, even those in the past.

Example:
If a product’s price changes from €100 to €120, all events will now display the current price of €120.

Best for:

• Analyses or personalizations based on the current catalog state

• Continuously updated analyses

The update context is a paid option.

To activate it, contact your Piano Analytics account manager for pricing and activation details.

Creating and Managing a Catalog

Access

• Menu Data Management > Catalogs

Main Steps

1. Choose the catalog type

   • Standard: pre-configured template recommended by Piano (fixed key and properties)

   • Custom: configure your own reconciliation key and enriched properties

2. Enter main information

   • Display name: name of the catalog as shown in the interface

   • Context: snapshot or update (see above)

   • Reconciliation key: an existing property in your data model, populated in your tagging

   • Case sensitivity: whether the matching is case-sensitive or not

   • Data Feed Type: method for importing your business catalog (API, sFTP, or manual CSV import via the interface)
     This choice determines how you’ll import your data (see Data Import for details).

   • Alerting: email notification in case of import failure (for CSV imports)

3. Define the catalog structure

   • Reconciliation key (e.g., product_id)

   • Enriched properties (e.g., name, category, price)

Tip: For Snapshot context, enriched properties must already exist in your data model. For Update, you can create them during configuration.

For advanced details (property management, limits, validations), see the appendix at the end of the doc.

Data Import

Three import modes are available:

• The interface guides you on the expected format and provides an example matching your structure.

• Automatic verification of imported files (column presence, format errors, etc.).

For exact formats, example files, error handling, see the appendix.

Monitoring and Alerts

• Processing report: view the latest import errors (by import mode).

• Preview data: see the last 10 imported rows and filter by a specific key.

Use Cases

Snapshot context

1. Sales analysis by collection (e-commerce)

Problem: You want to measure the performance of each collection at a specific point in time, even when prices or ranges change.
Solution:

• Collect only the product_id during purchases.

• Use a Snapshot catalog with properties like Product Name, Collection, Price.

• Historical reports will always reflect the values (e.g., price) at the time of purchase.

2. Engagement tracking for a limited-time offer (media)

Problem: You launch a special offer on certain content and want to keep track of the offer’s status at each interaction.
Solution:

• Collect the content_id for each view.

• Use a Snapshot catalog with properties like Content Name, Offer Type.

• Analyze the impact of the offer, even after modifications or expiration.

Update context

1. Dynamic user experience personalization (e-commerce)

Problem: You want all analyses to reflect the latest version of your catalog (e.g., availability, price, category).
Solution:

• Collect product_id at every interaction.

• Use an Update catalog with properties like Price, Availability.

• All analyses and segments use the current catalog state, even for past events.

2. Continuous editorial category updates (media)

Problem: Your content sections change regularly and you want your analyses to always be up to date.
Solution:

• Collect content_id for each consultation.

• Use an Update catalog with the Section property.

• Dashboards always reflect the current section, even for older articles.

Other use cases

• For E-commerce/Retail: Product names, categories, brands, colors, sizes, prices, margin information, stock levels.

• For Media/Publishing: Article titles, author names, publication dates, content categories, subscription types, paywall status.

• For Financial Services: Account types, investment product names, risk profiles, service tiers.

• For Travel/Hospitality: Property names, room types, destinations, amenity lists.

FAQ

Q: I want to use a standard catalog, but it’s grayed out. Why?
A: The template is already in use for the organization, or the reconciliation key is not validated. Check the property list in Data Management.

Q: Why doesn’t a property appear when creating a Snapshot catalog?
A: Only “processed” properties that are not of type array object are available.

Q: What happens if an enriched property is also present in my tagging?
A:

• Snapshot: If the reconciliation key doesn’t exist, the tagging value is kept. If it exists, the catalog value overwrites the tagging value.

• Update: The tagging property is never taken into account.

Q: Who can use the Update context?
A: The Update context is a paid option. Contact your account manager for more information.

Glossary

Advanced Details (Appendix)

Creation and Management – Details

• Standard vs. Custom

  • Standard: templates provided by Piano with fixed key and properties, fixed context.

  • Custom: freely choose the reconciliation key (beware of the 2 million unique values/day limit), customizable enriched properties.

• Display name

  • Customizable for custom catalogs, fixed for standard ones.

• Reconciliation key

  • Must exist in your data model and be populated in the tagging.

  • Is String or Integer.

  • Case sensitivity: defines if matching is case-sensitive (cannot be changed after creation).

• Enriched properties

  • Snapshot: must be pre-declared in the data model, simple type (not array object), and “processed.”

  • Update: can be created during catalog configuration, available later in the “Properties” tab of Data Management.

  • Must share the same scope as the reconciliation key.

• Data Feed Type

  • API: programmatic import via Piano endpoints.

  • sFTP: automated import by depositing CSV files on a dedicated server.

  • Manual import (UI): drag and drop or file selection directly in the interface.

• Alerting

  • Email notification system configurable for CSV imports (drag & drop or sFTP).

Import – Details

• API

  • Possible to import line by line (JSON) or grouped (ndJSON).

  • Limits: 100KB/line, 1GB total for ndJSON.

  • Token authentication, endpoint and payload example provided in the interface.

  • Developer documentation is available here.

• sFTP

  • Dedicated server created on request via Piano Analytics support.

  • CSV files, max 5GB (1GB recommended for performance).

  • Must follow the schema defined at catalog creation.

• Manual import (UI)

  • CSV file, max 10MB.

  • Downloadable or copyable schema from the interface.

  • Automatic verification: presence of reconciliation key, property consistency, preview of the first 10 rows.

  • Notifications in case of error or missing columns.

• Error handling

  • Processing report available for each import, differentiated by import mode.

  • Email alert in case of failure (if configured).

Limitations and Tips

• Limit of 2 million unique values per day on the reconciliation key: beyond this, the catalog may be paused.

• Enriched properties: a property can only be enriched in one catalog at a time.

• Modification: the reconciliation key and context cannot be changed after catalog creation.

• Availability:

  • Snapshot context: included at no extra cost.

  • Update context: paid option, contact your account manager.

For any questions, refer to the FAQ or contact your Piano Analytics support if needed.