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 for queries and to enrich usage 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.

By making these associations through the Event Protocol, the Coveo Platform can 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 that has to be sent, as the platform automatically supplements it behind the scenes. The enriched data also improves the contextual accuracy of event tracking by providing more detailed and relevant information for logged commerce events.

Use the Storefront associations (platform-ca | platform-eu | platform-au) panel to associate a catalog entity with the target tracking ID and locale.

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.

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:

  • <SOLUTION> is the product discovery solution that this particular query pipeline supports. The supported values are search, listing, or recommendations.

  • <TRACKING_ID> is the tracking ID (registered by a property) that this query pipeline supports. A tracking ID can be up to 100 characters in length, so it may be truncated to fit the query pipeline name’s 50-character limit.

  • <HASH_OF_THE_TRACKING_ID> is a deterministic 8-character hash of the tracking ID. The inclusion of the tracking ID ensures readability (even if truncated), while the hash prevents name collisions.

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.