Storefront setup and concepts

To effectively log commerce events, build your commerce interfaces, and use the Coveo Merchandising Hub (CMH), it’s important to properly define your storefronts, including their specific language, country, and currency combinations.

Note

For information on how to index products and manage your product catalog in a multi-brand, multi-language, multi-country, and/or multi-currency environment, see Optimize Catalog sources for multi-language and multi-brand setups.

Coveo for Commerce uses different mechanisms and tools to implement these concepts in your Coveo organization. Implementing these ensures that data is well segmented and that the Coveo for Commerce solution can provide relevant and accurate outputs based on the specific storefront variations a visitor interacts with.

This article provides an overview of the mechanisms that must be implemented to effectively track commerce events and query the Commerce API, as well as the typical management flow to follow:

Map your storefront architecture to Coveo

To effectively track commerce events, use the Commerce API, and manage product discovery through the CMH, you need to set up your storefronts in a way that’s compatible with Coveo.

In Coveo for Commerce, storefronts are organized into properties, and each property can support multiple locales. For example, if you have two storefronts—one in Canada and one in the United States—your Coveo setup would include two properties, one for each storefront.

Each property can have multiple locales. For example, if your Canadian storefront supports both English and French, you would have two locales under the Canadian property: en-CA-CAD and fr-CA-CAD. Each storefront/locale combination would have its own commerce catalog representing the products available for that specific combination.

The following diagram shows how the Barca brand’s storefront architecture could be set up in Coveo for Commerce, considering the following variations:

  • Two storefronts: Canada storefront and USA storefront

  • Two currencies: CAD and USD

  • Different supported languages for each storefront:

    • Canada storefront: English and French

    • USA storefront: English and Spanish

Diagram showing the declination of storefront setup to Coveo’s standards | Coveo for Commerce

Tracking ID

A Coveo organization can serve many ecommerce sites or applications, but all of the events in a user’s journey should be tied together for accurate data analytics and consistency.

tracking IDs segregate the data gathered from each of these sites or applications to ensure personalized and relevant output from your Coveo Machine Learning (Coveo ML) models, usable reporting, and clear merchandising actions. Each tracking ID points to a specific storefront, creating a way to bucket events that belong to different user journeys.

The tracking ID is defined when sending events to the Coveo Platform. Interfaces built with the Coveo Headless library or Atomic library automatically include the tracking ID in the events they send. While tracking ID values are specified when sending usage analytics events, each value that’s sent must be registered using a Property in your Coveo organization. See Properties for more information.

In the context of the Coveo Merchandising Hub (CMH), the management of the product discovery solutions is segmented by tracking ID. This means that merchandising actions, such as boosting products or creating rules, are specific to each tracking ID.

See What’s a tracking ID? for more information about tracking IDs.

Properties

Properties allow the management of tracking IDs within a Coveo organization. A property consists of a user-readable display name that simplifies the management and analysis of data across different sites or applications.

More precisely, you must use properties to:

  • Register new and existing tracking IDs.

  • Create relevant display names for tracking IDs. This is useful when you have multiple tracking IDs and you want to easily identify them when analyzing data.

  • Deregister and delete tracking IDs.

While tracking ID values are specified when sending usage analytics events, properties are managed through the Properties (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

Each tracking ID used in your usage analytics events must be registered as a property in your Coveo organization to allow for proper data tracking and interpretation.

Example

Your Coveo organization powers two brands that each have their own storefronts: Barca sports and Barca parts.

Usage analytics events logged from these storefronts are sent with the following tracking IDs:

  • barca_sports_us

  • barca_sports_ca

To allow for accurate data tracking and analysis, you create two properties to register these tracking IDs:

  • Barca Sports US

  • Barca Sports CA

If a tracking ID is sent in an event but isn’t registered, the event will still be logged, though it will appear as Invalid in the Event browser. This means that the tracking ID wasn’t recognized as a property, preventing accurate data segmentation and making it harder to analyze the source of the event.

For more information on how to manage properties, see Properties.

Locale

A given ecommerce site or application can support many languages, countries, and/or currencies, resulting in variations in product attributes like names, descriptions, and prices.

The Coveo Platform addresses this complexity by utilizing locales to distinguish unique combinations of language, country, and currency.

Locales are defined by a combination of the values of the language, country, and currency codes sent in Commerce API requests.

Locales allow for reporting according to the language, country, and currency of the user’s experience, as well as managing product discovery solutions for each language, country, and currency permutation within the Coveo Merchandising Hub (CMH).

Notes
  • A storefront can have multiple locales associated with it.

  • Locales are storefront parameters, not visitor browser parameters. For example, if a visitor's browser default language is set to German, and they’re browsing an English site, the locale language is en.

    Similarly, a visitor located in Germany browsing a US-based storefront that sells products in American dollars would have their locale tracked with the country set to US and the currency set to USD, even though they’re physically located in a country that uses a different currency.

Locales are defined for every potential combination of supported language, country, and currency that your ecommerce sites or applications support.

Example

Your Coveo organization powers two brands: Barca sports and Barca parts.

You operate in two different countries: United States and Canada. In the United States, you only support English, and in Canada, you support both English and French.

Therefore, you have three different locales:

  • en-US-USD

  • en-CA-CAD

  • fr-CA-CAD

Storefront associations

There’s a 1:1 relationship between a Catalog source and commerce catalog. This means that you should have a combination of a Catalog source and a commerce catalog for each language, country, currency, and brand you’re selling your products in.

A single tracking ID can apply to multiple locale combinations. For example, if you have a tracking ID identifying a storefront for a brand that sells products in both English and French in Canada, you would have a single tracking ID associated with two locales: en-CA-CAD and fr-CA-CAD.

Storefront associations let you manage the relationship between properties, locales, and commerce catalogs.

This allows the Coveo Platform to automatically infer the catalog ID targeted by a property and locale combination. So, there’s no need to specify the catalog ID when authenticating commerce requests.

For more information on storefront associations, see Storefront associations.

Management flow

To properly manage the properties, locales, and storefront associations in your Coveo organization and data tracking, you’ll typically follow these steps:

  1. Map your storefront architecture to Coveo by defining the properties that will be used to segment your data. Each storefront should have a unique property associated with it.

  2. Define the tracking IDs that will be used to track events in your commerce site or application.

  3. Register the tracking IDs using the Properties (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console. Give each tracking ID a relevant display name to easily identify it when analyzing data.

  4. Define the storefront associations for each property and locale combination using the Storefront associations (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

  5. Build your commerce interfaces and implement commerce event tracking in your commerce site or application.