Index content using the Coveo app for Shopify
Index content using the Coveo app for Shopify
The Coveo AI Search & Discovery app aims to automate as much of the onboarding process as possible, requiring minimal intervention on your part. This article lists a few scenarios that require you to manually sync your Shopify product catalog with Coveo and provides an overview of the resources created during the synchronization process.
When to manually sync your catalog
You must manually launch a sync of your Shopify product catalog with Coveo in the following situations:
-
You first link your store to your Coveo organization
-
You add or delete a new market
-
You add or delete a country within a market
-
You add or delete a language within a market
-
You change a market’s base currency
-
You change your multi-market domain setup
-
You add, change, or delete product or variant metafields, or update which ones to use as Coveo custom fields or facets
-
You change a store domain
Indexing prerequisites
The Coveo Platform will only index Shopify products that meet the following prerequisites:
-
Their Status is set to Active.
-
They are published to the Online Store.
How Coveo handles Shopify variants
In Shopify, you can define a product’s variants as options when you configure the product.
The Coveo Platform indexes every Shopify variant as a separate item, with the variant options appended to the ec_name field of each one.
If you have more than one variant option, the Coveo Platform indexes an item for each combination.
All Shopify variants are indexed as product catalog object items, and they’re grouped together using the ec_item_group_id field.
The product Relaxed Top is configured with the following variant options:
-
Color (red, blue, and yellow)
-
Size (S, M, and L)
The Coveo Platform indexes items with the following ec_name values:
-
Relaxed Top - Red - S -
Relaxed Top - Red - M -
Relaxed Top - Red - L -
Relaxed Top - Blue - S -
Relaxed Top - Blue - M -
Relaxed Top - Blue - L -
Relaxed Top - Yellow - S -
Relaxed Top - Yellow - M -
Relaxed Top - Yellow - L
The Coveo Platform doesn’t create fields for each variant option. If needed, you can use Shopify metafields to pass the variant option values to the index as Coveo fields. If you do, make sure that you select these fields to index when you sync your Shopify product catalog.
Resources
This section provides an overview of the resources created in your Coveo organization when you sync your Shopify product catalog using the Coveo AI Search & Discovery app.
Sources
When you sync your Shopify product catalog with the Coveo Platform, the Coveo AI Search & Discovery app uses the Shopify GraphQL Admin API to retrieve your market languages, regions, and base currencies.
|
Note
At the moment, the app only supports base currencies, not local currencies. |
In your Coveo organization, the app then creates one GraphQL API source per market and language combination to index your products. These sources use the following naming scheme:
shopify <MARKET_NAME> <SHOP_NAME> <LANGUAGE> <CURRENCY> - <RANDOM_UUID>For example, a source could be named as follows: shopify canada docs_coveo en cad - 1c3386f2-ec73-4716-b6df-b4b7963a8743.
Every source is automatically configured for Commerce and uses the default source-update-schedule. The app also creates a matching catalog entity for each source and storefront associations to associate your catalog entities to your storefronts in the target locales.
Each of these sources scans your Shopify store for products and their variants, indexing the active ones. You can therefore have multiple Coveo items for a single Shopify product or variant, each corresponding to a specific market and language combination.
You have three markets: the US, Canada, and a simplified "Europe" that consists of France and Germany. These markets have the following language pairings:
-
US: English
-
Canada: English, French
-
Europe: French, German
There will be five sources:
Catalog entities
A catalog entity is a commerce-specific resource that establishes a catalog data structure and enables Coveo Machine Learning (Coveo ML) and Coveo Analytics reporting.
The Coveo AI Search & Discovery app creates one catalog entity per source. Each catalog entity is based on the same name as its matching source, but with a 50-character limit.
For example, if the source is shopify canada docs_coveo en cad - 1c3386f2-ec73-4716-b6df-b4b7963a8743, then the catalog entity would be named shopify canada docs_coveo en cad - 1c3386f2-ec73-4.
You have three markets: the US, Canada, and a simplified "Europe" that consists of France and Germany. These markets have the following language pairings:
-
US: English
-
Canada: English, French
-
Europe: French, German
There will be five catalog entities to match the five sources:
Fields
A field is an index-wide container that holds information about each item.
When syncing your Shopify product catalog with Coveo, the Coveo AI Search & Discovery app automatically indexes standard commerce fields. These fields are preselected by default and can’t be unselected.
|
|
Note
If any of the fields in your Coveo organization have the same names as the standard commerce fields, but their types don’t match, you’ll see an error message. You can’t edit field types once they have been created in the Coveo Administration Console. You’ll have to delete and recreate them with the expected types. |
Besides the standard fields, you can index up to 650 additional Shopify product metafields as Coveo custom fields to enhance the search experience.
The app also lets you select which fields to use as facets in your search interface. You can only use fields that are explicitly facet-enabled when creating facets in your search interface.
Metafields
The Coveo Platform indexes Shopify metafields as Coveo fields.
Metafields can be used to pass product attributes that the platform wouldn’t index otherwise, so that you can display them in product discovery solution interfaces or create merchandising rules targeting these attributes.
One use case is leveraging metafields to pass Shopify variant option values to the index as Coveo fields. When the Coveo Platform indexes product variants, the variant options aren’t stored in their own fields. To use a specific variant option, you must create a metafield and set it for each variant.
Expand the following section to see an example of how to use a metafield to pass a variant option to your Coveo index.
Metafield example
In the Barca storefront, The Complete Snowboard product has five color variants: Dawn, Electric, Ice, Powder, and Sunset.
The Coveo Platform indexes the following product catalog object items:
-
The Complete Snowboard - Dawn
-
The Complete Snowboard - Electric
-
The Complete Snowboard - Ice
-
The Complete Snowboard - Powder
-
The Complete Snowboard - Sunset
However, the variant color values aren’t indexed in a field.
To target variants by color, you define a variant metafield called Snowboard color.
You then enter the color values in the Snowboard color metafield for each variant.
When you sync your Shopify product catalog, select the snowboard_color metafield.
After syncing your product catalog, the five variant items in your index will each have the snowboard_color field.
You can now create a ranking rule in the CMH Search manager to boost items whose snowboard_color is Ice.
Delete and recreate fields
You can’t edit field types in the Coveo Administration Console.
If there’s a type mismatch between the standard fields used by the app and fields in your Coveo organization with the same names, you’ll have to delete your existing fields and recreate them with the expected types.
For example, if you have an existing string-type field named ec_price, you’ll see an error when you try to sync because the app expects that field to be a decimal.
To delete and recreate fields:
-
In the Administration Console, delete any mappings that are related to the fields you want to replace.
Because mappings exist in all sources, you’ll have to delete the target mappings in all sources.
-
On the Fields (platform-ca | platform-eu | platform-au) page, select the field that you want to delete and click Delete in the Action bar, then click Delete again to confirm. You can’t select multiple fields at once in the Administration Console, so you’ll have to repeat this step for every field that you want to delete.
-
Add one or more new fields. Make sure that every new field uses the correct type.
-
Recreate any mappings related to the new fields.
You’ll have to recreate the target mappings in all sources.
Tracking IDs and properties
A tracking ID is a unique identifier, such as market_27852734695, which is used to link events so that they can be analyzed and attributed to the right product discovery solution.
A property is equivalent to one tracking ID, except that it has a user-readable display name, such as Europe.
The Coveo AI Search & Discovery app creates one tracking ID and matching property per market.
Storefront associations
A storefront association connects a catalog entity with a specific tracking ID and locale.
The Coveo AI Search & Discovery app creates one storefront association per market and locale combination.
You have three markets: the US, Canada, and a simplified "Europe" that consists of France and Germany. Based on the languages available in each market, there are five sources and therefore five catalog entities.
Both of the European countries in this example have two locales, one for each language that’s configured for the market.
For example, Germany has the locales de-DE-EUR and fr-DE-EUR.
In total, there will be seven storefront associations:
Query pipelines
A query pipeline is a set of rules that modify queries.
The Coveo AI Search & Discovery app creates one query pipeline for each market and product discovery solution combination.
You have three markets: the US, Canada, and Europe. Coveo for Commerce has three product discovery solutions: search, product listings, and recommendations.
There will be ten query pipelines, including the default:
Source update schedule
By default, if you enable automatic catalog synchronization, the Coveo sources are updated according to the following schedule:
Very useful
Not really
Very useful
Not really