Storefront associations

This is for:

System Administrator Developer

A storefront association is a Coveo Platform configuration that connects a catalog entity with a specific tracking ID and locale.

The Coveo Platform uses storefront associations to automatically identify the appropriate catalog ID in queries and to enrich Coveo Analytics events with product metadata. Because the platform resolves the appropriate catalog entity for content retrieval and event enrichment, you don’t need to specify the catalog ID when making queries or logging events using the Event Protocol. This allows the Coveo Platform to enrich event data with key metadata from the Coveo catalog, such as ec_category, ec_brand, and ec_item_group_id. This reduces the amount of data you must send and provides more detailed and relevant information for logged commerce events.

Storefront associations are required for the proper functioning of Coveo for Commerce implementations.

Important

If you delete a storefront association, you’ll need to recreate any Coveo Personalization-as-you-go machine learning model that’s linked to the storefront.

Prerequisites

To create a storefront association, you need at least:

  • A source that holds your product data (for example, a Catalog source).

  • A catalog entity that’s linked to the source.

  • A property.

  • The following privileges in your Coveo organization:

    Action Service - Domain Required access level

    Create storefront associations

    Search - Query pipelines

    Create

    Commerce - Catalogs

    Edit

    Analytics - Property

    View

    Edit storefront associations

    Commerce - Catalogs

    Edit

    Analytics - Property

    View

    View storefront associations

    Commerce - Catalogs

    View

    Analytics - Property

    View

Create a storefront association

  1. Access the Storefront associations (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console.

  2. Click Create an association.

  3. Under Property, select the property tied to the tracking ID that identifies the storefront you want to use for this association.

  4. Under Locale, select the locale you want to use for this association. A locale is composed of:

    • An ISO 639-1 language code (for example, en for English).

    • An ISO 3166-1 alpha-2 country code (for example, US for the United States).

    • An ISO 4217 currency code (for example, USD for US dollar).

  5. Under Catalog, select the catalog entity that contains the products for a given storefront and locale combination.

  6. (If available) You can optionally use the Project selector to associate your storefront association with one or more projects.

  7. Click Save.

Example

You have two storefronts: one that targets customers in Canada and displays product prices in Canadian dollars, and another storefront that targets customers in the United States and displays product prices in US dollars.

To handle these two storefronts, you have two Catalog sources in your Coveo organization: one for the Canadian storefront and another for the US storefront.

Therefore, you must create two storefront associations:

Storefront associations and query pipelines

When you define a storefront association, the Coveo Platform will automatically create three query pipelines and their associated conditions, one for each product discovery solution.

Note

If these query pipelines already exist for a given tracking ID, then the Coveo Platform won’t create duplicates.

For example, if your storefront consists of a single site with multiple language and currency options, you’ll associate multiple locales with a single tracking ID. In this case, the Coveo Platform will only create these query pipelines for the first storefront association that you define with this tracking ID.

Each of these query pipelines handle queries sent from one of the product discovery solution interfaces that use the tracking ID defined in the storefront association and ensure that these queries send the right information to the Commerce API.

The query pipeline names and descriptions use the following format:

  • Query pipeline name (maximum 50 characters): cmh-<SOLUTION>-<TRACKING_ID>-<HASH_OF_THE_TRACKING_ID>

  • Query pipeline description: <SOLUTION>-<TRACKING_ID>

where:

Example

Your tracking ID is market_27852570855. After you define a storefront association, the following query pipelines are created within your Coveo organization:

Name Description

cmh-listing-market_27852570855-0f3825a5

listing-market_27852570855

cmh-search-market_27852570855-0f3825a5

search-market_27852570855

cmh-recommendations-market_27852570855-0f3825a5

recommendations-market_27852570855

Query pipeline conditions

query pipeline conditions route queries originating from different product discovery solution interfaces to the correct query pipeline. For example, when a user sends a query from the search box, the condition will route the query to the query pipeline dedicated to the Search solution.

These conditions are configured when the query pipelines are created. They use a naming convention that’s based on the solution that the query pipeline supports, as shown in the following table:

Product discovery solution Query pipeline condition

Search

Context[commerce-api] is Search and Context[trackingId] is <TRACKING_ID>

Product listings

Context[commerce-api] is Listing and Context[trackingId] is <TRACKING_ID>

Recommendations

Context[commerce-api] is Recommendations and Context[trackingId] is <TRACKING_ID>

where <TRACKING_ID> is the tracking ID used in the request to the Commerce API.

Example

Your tracking ID is market_27852570855. After you define a storefront association, your query pipelines have the following conditions:

Name Condition

cmh-search-market_27852570855-0f3825a5

Context[commerce-api] is Search and Context[trackingId] is market_27852570855

cmh-listing-market_27852570855-0f3825a5

Context[commerce-api] is Listing and Context[trackingId] is market_27852570855

cmh-recommendations-market_27852570855-0f3825a5

Context[commerce-api] is Recommendations and Context[trackingId] is market_27852570855

Query pipelines for Product listings

For each query pipeline associated with the Product listings solution, you must configure a ranking weight query pipeline rule to optimize the ranking of products on product listing pages (PLPs).

In this ranking rule, set all the ranking factors to 0.

Listings ranking rule in the Coveo Administration Console| Coveo

Storefront associations and authentication

Once you’ve set up the necessary storefront associations, you can authenticate both search and analytics requests using a single search token or API key that grants the Allowed access level on the Execute Queries domain and the Push access level on the Analytics Data domain in the target Coveo organization.

For more details on authenticating requests, see Authenticate commerce requests.

Tip

You no longer need to generate API keys through the Catalogs (platform-ca | platform-eu | platform-au) page, which would enforce the catalog ID value in the API keys. A single search token or API key can be used across many catalog entities.