DocumentationCommerceLive Search Guide

Set up for success with Live Search

Last update: Mon May 13 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

Adobe Commerce Live Search and Catalog Service work together to provide a performant, relevant, and intuitive search solution to allow your customers to find exactly what they need, fast. Specifically, Catalog Service surfaces your catalog data for SaaS services, such as Live Search to use.

This article provides step-by-step instructions for implementing Live Search with Catalog Service.

IMPORTANT
When it comes to site search, Adobe Commerce gives you options. Be sure to read Boundaries and Limits before implementing, to ensure Live Search is a fit for your business needs.

Audience

This article is intended for the developer or systems integrator on your team who is responsible for installing and configuring your Adobe Commerce instance.

Requirements

Supported platforms

  • Adobe Commerce on Cloud (ECE) : 2.4.4+
  • Adobe Commerce on-prem (EE) : 2.4.4+

Workflow overview

At a high level, onboarding Live Search requires that you:

Live Search Workflow

1. Install the Live Search extension

Live Search is installed as an extension from Adobe Marketplace through Composer. After you install and configure Live Search, Adobe Commerce begins sharing search and catalog data with SaaS services. At this point, Admin users can set up, customize, and manage search facets, synonyms, and merchandising rules.

NOTE
As of Live Search 3.0.2, the Catalog Service extension is bundled in with the Live Search installation.

  1. Confirm that cron jobs and indexers are running.

    note important
    IMPORTANT
    Due to the Elasticsearch 7 end-of-support announcement for August 2023, it is recommended that all Adobe Commerce customers migrate to the OpenSearch 2.x search engine. For information about migrating your search engine during a product upgrade, see Migrating to OpenSearch in the Upgrade Guide.

  2. Download the live-search package from the Adobe Marketplace.

  3. Run the following from the command line:

    code language-bash 
    composer require magento/live-search

    If you are adding the Live Search extension to a new Adobe Commerce installation, run the following to disable OpenSearch and related modules, and install Live Search. Then proceed to step 4.

    code language-bash 
       bin/magento module:disable Magento_Elasticsearch Magento_Elasticsearch7 Magento_OpenSearch Magento_ElasticsearchCatalogPermissions Magento_InventoryElasticsearch Magento_ElasticsearchCatalogPermissionsGraphQl

    If you are adding the Live Search extension to an existing Adobe Commerce installation, run the following to temporarily disable the Live Search modules that serve storefront search results. Then proceed to step 4:

    code language-bash 
       bin/magento module:disable Magento_LiveSearchAdapter Magento_LiveSearchStorefrontPopover Magento_LiveSearchProductListing

    Elasticsearch continues to manage search requests from the storefront while the Live Search service synchronizes catalog data and indexes products in the background.

  4. Run the following:

    code language-bash 
    bin/magento setup:upgrade

  5. Verify that the following indexers are set to “Update by Schedule”:

    • Product Feed
    • Product Variant Feed
    • Catalog Attributes Feed
    • Product Prices Feed
    • Scopes Website Data Feed
    • Scopes Customer Groups Data Feed
    • Categories Feed
    • Category Permissions Feed

  6. If you are installing Live Search on a new Commerce instance, you are done and can skip to the 2. Configure API keys section. If you are installing Live Search to an existing Commerce instance, proceed to the next step.

  7. Run the following commands to enable the Live Search extension, disable OpenSearch, and run setup.

    code language-bash 
    bin/magento module:enable Magento_LiveSearchAdapter Magento_LiveSearchStorefrontPopover  Magento_LiveSearchProductListing
    code language-bash 
    bin/magento module:disable Magento_Elasticsearch Magento_Elasticsearch6 Magento_Elasticsearch7 Magento_ElasticsearchCatalogPermissions Magento_InventoryElasticsearch
Magento_ElasticsearchCatalogPermissionsGraphQl
    code language-bash 
    bin/magento setup:upgrade

2. Configure API keys

The Adobe Commerce API key and its associated private key are required to connect Live Search to an installation of Adobe Commerce. The API key is generated and maintained in the account of the Commerce license holder, who can share it with the developer or systems integrator. The developer can then create and manage the SaaS Data Spaces on behalf of the license holder. If you already have a set of API keys, you do not need to regenerate them.

Learn how to configure your API keys in the Commerce Services Connector article.

3. Sync your catalog data synchronize-catalog-data

Live Search moves catalog data to Adobe’s SaaS infrastructure. The data is indexed and search results are delivered from this index directly to the storefront. Depending on the size and complexity, indexing can take from 30 minutes to a couple of hours.

To begin the initial sync of your catalog data to SaaS services, run the following commands in this order:

bin/magento saas:resync --feed productattributes
bin/magento saas:resync --feed products
bin/magento saas:resync --feed scopesCustomerGroup
bin/magento saas:resync --feed scopesWebsite
bin/magento saas:resync --feed prices
bin/magento saas:resync --feed productoverrides
bin/magento saas:resync --feed variants
bin/magento saas:resync --feed categories
bin/magento saas:resync --feed categoryPermissions

When you run these commands, the initial sync of your catalog data to SaaS services begins.

WARNING
While the data is indexed and synchronized, the search and category browse operations are not available in the storefront. Depending on the size of your catalog, the process can take at least an hour from the time cron runs to synchronize your data to SaaS services.

Monitor sync progress

You can view the data that is synchronized and shared using the Data Management Dashboard. This dashboard provides valuable insights into the availability of product data for your storefront, ensuring it can be promptly displayed to your shoppers.

Data Management Dashboard

Future product updates

After the initial synchronization, it can take up to 15 minutes for incremental product updates to become available to storefront search. To learn more, see Indexing - Streaming Product Updates.

4. Verify the data was exported verify-export

To verify that the catalog data has been exported from your Adobe Commerce instance and is synchronized for Live Search, you have a couple of options:

  • Look for entries in the following tables:

    • catalog_data_exporter_products
    • catalog_data_exporter_product_attributes

  • Use the GraphQL playground with the default query to verify the following:

    • The returned product count is close to what you expect for the store view.
    • Facets are returned.

For additional help, see Live Search catalog not synchronized in the Support Knowledge Base.

5. Configure the data

Getting your product data configured correctly ensures good search results for your customers. In this section, you enable the product listing widgets and assign categories and attributes.

Enable Product Listing Widgets

When you install Live Search 4.0.0+, Product Listing Widgets are enabled by default. When widgets are enabled, a different UI component is used for the search results page and category browse Product Listing Page. This UI component makes direct calls to the Catalog Service API, which results in faster response times.

If you have a Live Search version older than 4.0.0+, you need to manually enable the Product Listing Widget.

  1. From the Admin, go to Stores > Settings > Configuration.

  2. Under Live Search, select Storefront Features.

  3. Set Enable Product Listing Widgets to Yes.

    Enable Product Listing Widgets

When you change this configuration, the message Page cache is invalidated appears. You need to flush the Magento Cache to save your change.

  1. Access the Cache Management page by doing one of the following:

    • Click the Cache Management link in the message above the workspace.
    • On the Admin sidebar, go to System > Tools > Cache Management.

  2. Select the Configuration Cache Type and click Flush Magento Cache.

    Changes to the storefront are immediate after you flush the cache.

Assign categories

Products returned in Live Search must be assigned to a category. In Luma, for example, products are put into categories such as “Men”, “Women”, and “Gear”. Subcategories are also set up for “Tops”, “Bottoms”, and “Watches”. This allows for better granularity when filtering.

Searchable and filterable fields

Products are assigned attributes that can be used for searching and filtering. Attributes are things such as “Color”, “Size”, “Material Type”. With these attributes, users can look for “green tops”. Each product may have many attributes defined in the Commerce Admin.

Each of these attributes can be defined as “searchable” in the Admin. When set as “searchable”, those attributes are available to be searched by Live Search.

Facets are product attributes that are defined in Live Search to be filterable. Any filterable attribute may be set as a facet in Live Search but there are limits to how many facets can be searched at one time.

Synonyms are terms that you can define to help guide users to the correct product. Users looking for pants might type in “trousers” or “slacks”. You can set synonyms so that these search terms will get users to the “pants” results.

6. Test the connection test-connection

With your catalog data now in SaaS, test to make sure product data is returned in the following scenarios:

  • The Search box returns results correctly
  • Category browse returns results correctly
  • Facets are available as filters on search results pages

If everything works correctly, Live Search is installed, connected, and ready to use.

If you encounter problems in the storefront, check the var/log/system.log file for API communication failures or errors on the services side.

To allow Live Search through a firewall, add commerce.adobe.io to the allowlist.

7. Customize for your storefront

You have installed the Live Search extension, synced, validated, and configured your data. Now, you will want to ensure that the Live Search widgets conform to your store’s look and feel.

You can style the popover and PLP widgets by defining custom CSS rules as needed. See Styling Popover Elements and Product Listing Page Widget.

If you wish to extend the functionality of the widgets, the source code for each is available in a public repo.
In this scenario, you can customize the JavaScript for your own needs and then host your custom code on your CDN. This custom script communicates with the Live Search service and returns the results like normal, allowing you to control the functionality of the widget.

Updating Live Search update

Before updating Live Search, run the following from the command line to check the version of Live Search that is installed:

composer show magento/module-live-search | grep version

To update Live Search, run the following from the command line:

composer update magento/live-search --with-dependencies

To update to a major version such as from 3.1.1 to 4.0.0, edit the project’s root Composer .json file as follows:

  1. If your currently installed magento/live-search version is 3.1.1 or below, and you are upgrading to version 4.0.0 or higher, run the following command before the upgrade:

    code language-bash 
    bin/magento module:enable Magento_AdvancedSearch

    For information about the currently installed magento/live-search version, run the following command:

    code language-bash 
    composer show magento/live-search

  2. Open the root composer.json file and search for magento/live-search.

  3. In the require section, update the version number as follows:

    code language-json 
    "require": {
   ...
   "magento/live-search": "^4.0",
   ...
 }

  4. Save composer.json. Then, run the following from the command line:

    code language-bash 
    composer update magento/live-search --with-dependencies

Uninstalling Live Search uninstall

To uninstall Live Search, refer to Uninstall modules.

Live Search packages packages

The Live Search extension consists of the following packages:

Package
Description
module-live-search
Allows merchants to configure their search settings for faceting, synonyms, query rules, and so on, and provides access to a read-only GraphQL playground to test queries from the Admin.
module-live-search-adapter
Routes search requests from the storefront to the Live Search service and renders the results in the storefront.
- Category browse - Routes requests from the storefront top navigation to the search service.
- Global search - Routes requests from the quick search box in the upper-right of the storefront to the Live Search service.
module-live-search-storefront-popover
A “search as you type” popover replaces the standard quick search and returns data and thumbnails of top search results.

Live Search dependencies dependencies

The following Live Search dependencies are captured by Composer.

  • magento/module-saas-catalog
  • magento/module-saas-category
  • magento/module-saas-category-permissions
  • magento/module-saas-product-override
  • magento/module-saas-product-variant
  • magento/module-saas-price
  • magento/module-saas-scopes
  • magento/module-bundle-product-data-exporter
  • magento/module-catalog-inventory-data-exporter
  • magento/module-catalog-url-rewrite-data-exporter
  • magento/module-configurable-product-data-exporter
  • magento/module-parent-product-data-exporter
  • magento/module-gift-card-product-data-exporter
  • magento/module-bundle-product-override-data-exporter
  • data-services
  • services-id

Advanced concepts

The following sections provide more advanced topics when using Live Search and Catalog Service.

Endpoint

Live Search communicates through the endpoint at https://catalog-service.adobe.io/graphql.

As Live Search does not have access to the complete product database, Live Search GraphQL and Commerce core GraphQL will not have complete parity.

It is recommended to call the SaaS APIs directly - specifically the Catalog Service endpoint.

  • Gain performance and reduce processor load by bypassing the Commerce database/Graphql process
  • Take advantage of the Catalog Service federation to call Live Search, Catalog Service, and Product Recommendations from a single endpoint.

For some use cases, it maybe better to call Catalog Service for product details and similar cases. See refineProduct for more information.

If you have a custom headless implementation, check out the Live Search reference implementations:

If you do not use the default components, such as Search Adapter or widgets on Luma, or AEM CIF Widgets, eventing (clickstream data that feeds Adobe Sensei for Intelligent Merchandising and performance metrics) will not work out of the box and requires custom development to implement headless eventing.

The latest version of Live Search already uses Catalog Service.

Language support

Live Search widgets support the following languages:

Language
Region
Language Code
Magento Locale
Bulgarian
Bulgaria
bg_BG
bg_BG
Catalan
Spain
ca_ES
ca_ES
Czech
Czech Republic
cs_CZ
cs_CZ
Danish
Denmark
da_DK
da_DK
German
Germany
de_DE
de_DE
Greek
Greece
el_GR
el_GR
English
United Kingdom
en_GB
en_GB
English
United States
en_US
en_US
Spanish
Spain
es_ES
es_ES
Estonian
Estonia
et_EE
et_EE
Basque
Spain
eu_ES
eu_ES
Persian
Iran
fa_IR
fa_IR
Finnish
Finland
fi_FI
fi_FI
French
France
fr_FR
fr_FR
Galician
Spain
gl_ES
gl_ES
Hindi
India
hi_IN
hi_IN
Hungarian
Hungary
hu_HU
hu_HU
Indonesian
Indonesia
id_ID
id_ID
Italian
Italy
it_IT
it_IT
Korean
South Korea
ko_KR
ko_KR
Lithuanian
Lithuania
lt_LT
lt_LT
Latvian
Latvia
lv_LV
lv_LV
Norwegian
Norway Bokmal
nb_NO
nb_NO
Dutch
Netherlands
nl_NL
nl_NL
Polish
Poland
pl_PL
pl_PL
Portuguese
Brazil
pt_BR
pt_BR
Portuguese
Portugal
pt_PT
pt_PT
Romanian
Romania
ro_RO
ro_RO
Russian
Russia
ru_RU
ru_RU
Swedish
Sweden
sv_SE
sv_SE
Thai
Thailand
th_TH
th_TH
Turkish
Turkey
tr_TR
tr_TR
Chinese
China
zh_CN
zh_Hans_CN
Chinese
Taiwan
zh_TW
zh_Hant_TW

If the widget detects that the Commerce Admin language setting (Stores > Settings > Configuration > General > Country Options) matches a supported language, it defaults to that language. Otherwise, the widgets default to English.

Admins can also set the language of the search index, to help ensure better search results.

Widget code repository

The Product Listing Page widget and the Live Search field widget are both available for download from their github repository.

This allows developers to fully customize the functionality and styling. These users host the code themselves while still taking advantage of the Live Search service.

Inventory Management

Live Search supports Inventory Management capabilities in Commerce (formerly knows as Multi-Source Inventory, or MSI). To enable full support, you must update the dependency module commerce-data-export to version 102.2.0+.

Live Search returns a boolean noting whether a product is available within Inventory Management, but does not contain information about which source has the stock.

Price indexer

Live Search customers can use the new SaaS price indexer, which provides faster price change updates and synchronization time.

Price support

Live Search widgets support most but not all price types supported by Adobe Commerce.

Currently, basic prices are supported. Advanced prices that are not supported are:

  • Cost
  • Minimum Advertised Price

Look at API Mesh for more complex price calculations.

The price format supports the locale configuration setting within the Commerce instance: Stores > Settings > Configuration > General > General > Local Options > Locale.

Headless storefront support

Optionally, you might need to install the module-data-services-graphql module that expands the application’s existing GraphQL coverage to include fields required for storefront behavioral data collection.

composer require magento/module-data-services-graphql

This module adds additional contexts to GraphQL queries:

  • dataServicesStorefrontInstanceContext
  • dataServicesMagentoExtensionContext
  • dataServicesStoreConfigurationContext

PWA support

Live Search works with PWA Studio but users might see slight differences compared to other Commerce implementations. Basic functionality such as search and product listing page work in Venia but some permutations of Graphql might not work correctly. There might also be performance differences.

  • The current PWA implementation of Live Search requires more processing time to return search results than Live Search with the native Commerce storefront.
  • Live Search in PWA does not support event handling. As a result, search reporting nor intelligent merchandising will work.
  • Filtering directly on description, name, short_description is not supported by GraphQL when used with PWA, but they are returned with a more general filter.

To use Live Search with PWA Studio, integrators must also:

  1. Install livesearch-storefront-utils.

  2. Set the environmentId in the storeDetails object.

    code language-javascript 
    const storeDetails: StoreDetailsProps = {
    environmentId: <Storefront_ID>,
    websiteCode: "base",
    storeCode: "main_website_store",
    storeViewCode: "default",
    searchUnitId: searchUnitId,
    config: {
        minQueryLength: 5,
        pageSize: 8,
        currencySymbol: "$",
        },
    };

Cookies

Live Search collects user interaction data as part of its base functionality and cookies are used to store this data. When collecting any user information, the user must agree to store cookies. Live Search and Product Recommendations share the data stream and therefore the same cookie mechanism. Read more about it in Handle Cookie Restrictions.

recommendation-more-help
1d60634e-b73a-404a-be7a-4a2a36676055