About the search hub

This is for:

Developer System Administrator

By definition, a search hub is a Search API query parameter whose value is the identifier of the search interface from which a query originates. See searchHub (string) to access the reference documentation on the searchHub query parameter.

It’s essential that the value of the searchHub query parameter is filled with accurate information to:

This article aims at explaining how to make sure that the searchHub value is always filled with the proper information in a Coveo for Commerce use case.

Search hub basics

Requests to the Coveo Search API and the associated usage analytics events are tagged with a reference to the search interface the query originates from. That tag is called the search hub.

In requests to Coveo Usage Analytics (Coveo UA), the search hub value appears in the originLevel1 parameter.

In requests to the Search API

search hub value in Search API requests | Coveo

In requests to Coveo Usage Analytics (Coveo UA)

search hub value in Coveo UA requests | Coveo

Defining the search hub at the interface level

When building your user interfaces, such as search, listing, and recommendation interfaces with Coveo Platform's frameworks (that’s, Coveo Atomic library or Coveo Headless library), you can specify a search hub value at the interface level. Note that the value chosen for the search hub must be of the string data type.

Tip
Leading practice

We highly recommend setting a search hub at both the interface level and in the authentication.

When doing so, the searchHub value of all requests to the Search API originating from the interface will contain the value configured at the interface level.

Also, setting a search hub value at the interface level will be used to fill the value of the originLevel1 parameter for both click and search events originating from this interface, which is essential for accurate reporting and for computing attribution correctly.

Example

You create a search interface for which you configure the search hub to be coveo-storefront-search.

All queries originating from this search interface will contain a searchHub parameter, for which the value will be coveo-storefront-search.

Similarly, all click and search events performed from this interface will contain an originLevel1 parameter for which the value will be coveo-storefront-search.

Defining the search hub in Atomic interfaces

Depending on whether you want to define the search hub on a search interface or recommendation component using the Atomic framework, see the following documentation:

Example

The following code sample shows how you would set the search hub on a atomic-search-interface component:

<body>
  <atomic-search-interface
    search-hub="<SEARCH_HUB>"
  >
    <atomic-search-box></atomic-search-box>
    <!-- ... -->
  </atomic-search-interface>
</body>

Defining the search hub in Headless interfaces

To define the search hub on an interface built with the Headless framework, you must set the value when initializing the Headless engine. Depending on the Headless engine you want to initialize:

Engine Instructions

Search

Set the search hub value using the SearchConfigurationOptions object.

Recommendation

Set the search hub value using the RecommendationEngineConfiguration object.

Product Recommendation

Set the search hub value using the ProductRecommendationEngineConfiguration object.
Example

The following code sample shows how you would set the search hub using the SearchConfigurationOptions object.

import { buildSearchEngine, getOrganizationEndpoints } from '@coveo/headless';

export const headlessEngine = buildSearchEngine({
  configuration: {
    [...]
    search: {
      searchHub: "<SEARCH_HUB>",
    },
  },
});

Defining the search hub in the authentication

Any interface that relies on the Coveo Platform regularly performs authenticated HTTP requests against the Search API and Coveo UA, which means that you need to implement a query authentication method to authenticate the requests originating from that interface.

When initializing your interface, you must mention an authorization token that grants the Allowed access level on the Execute Queries domain and the Push access level on the Analytics Data domain in the target organization.

This can be done by either using an API key or a search token.

Both methods let you specify a search hub value, which we strongly recommend to protect the security of your content. See Ensure that authentication enforces search hub values for more details on the importance of enforcing a search hub in your authentication method.

When defining a search hub value within the authentication, this value takes precedence over the one defined at the interface level. This means that if you configure a specific search hub at the interface level, and another search hub in the authentication method responsible for authenticating queries originating from that search interface, the value of the searchHub parameter of the query will be the one configured in the authentication method.

Tip
Leading practice

We highly recommend setting a search hub at both the interface level and in the authentication.

Note that this behavior doesn’t apply to requests to Coveo UA. If the search hub defined at the interface level and the one defined in the authentication method differ, the one defined at the interface level will be used to fill the value of the originLevel1 parameter.

Example

When configuring your interface, you defined coveo-storefront-search to be the search hub value for this interface.

However, when configuring an authentication method to authenticate the requests originating from this interface, you added a search hub parameter for which the value is storefront.

Therefore, the searchHub parameter of requests to the Search API will be storefront, and the originLevel1 parameter of requests to Coveo UA will be coveo-storefront-search.

Therefore, to ensure consistency, we highly recommend that you configure the search hub in the authentication and ensure that the value matches the one setup at the interface level. For example, if you configured coveo-storefront-search to be the search hub value at the interface level, the search hub value enforced in the authentication method should also be coveo-storefront-search.

For information on how to configure your authentication method to authenticate requests to the Search API and Coveo UA see:

Note

Your authorization token requires the Allowed access level on the Execute Queries domain, as well as the Push access level on the Analytics Data.

Search hub naming conventions

In Coveo for Commerce implementations, there’s a specific naming convention that must be used to ensure that attribution is computed accurately.

Depending on the type of interface from which the event originates, the value of the search hub must contain:

Type of interface Contains the string

A search page

search

A product listing page

listing
Note

For recommendation components, the attribution mechanism is automatically managed by tracking a unique ID throughout the actions leading to a product being added to a cart or purchased. Therefore, there’s no specific naming convention to use when choosing a search hub value for your recommendation component, but note that it’s a good practice to add recs in the component’s search hub value (for example, home_page_recs).

However, the identifier value of the recommendation component is used for reporting purposes. Specifically, the Coveo UA service utilizes the recommendation parameter value from queries originating from a particular recommendation component to generate reports on the performance of that specific component.

To ensure clarity and easy recognition, we strongly recommend assigning a meaningful and recognizable value as the identifier for your recommendation component.

You can achieve this by setting the id property for your recommendation component. If you’re using Headless, for instance, you can specify the component’s ID by utilizing the id property when initializing the RecommendationList controller.

Query routing

Every query submitted to the Coveo Platform must pass through a query pipeline. Specifically, queries originating from a particular interface need to be directed to a dedicated query pipeline.

Query routing refers to the mechanism used to ensure queries originating from a given search interface are routed to the proper query pipeline (see Query pipeline routing mechanisms and rules).

The recommended and most flexible mechanism is the condition-based routing mechanism. Condition-based routing, as indicated by its name, relies on the usage of a query pipeline condition.

By using the search hub value configured at the interface level and in the authentication token, you can configure a condition on the query pipeline to which queries originating from the interface must be routed to ensure that the proper query pipeline is used.

Example

When configuring your interface and authentication token, you defined coveo-storefront-search to be the search hub value.

You want the coveo-storefront query pipeline to handle queries originating from the coveo-storefront-search interface.

Therefore, on the coveo-storefront query pipeline, you define the following condition: search hub is coveo-storefront-search.

Validate the search hub and query pipeline

To make sure that the correct search hub value is used in requests to the Search API and Coveo UA, and that queries are routed to the right query pipeline, you can perform the following validations:

To validate the search hub and query pipeline value in requests to the Search API

  1. Access the interface for which you want to validate the search hub and query pipeline value.

  2. Open your web browser’s developer tools.

    Note

    The examples in this article use the Google Chrome developer tools. For browser-specific information, see:

  3. Select the Network tab.

  4. Depending on whether you’re inspecting requests originating from a search interface, recommendation component, or listing page, perform the following:

    • For a search interface, in the search box, perform a query.

    • For a recommendation interface, open a page that incorporates a recommendation interface (for example, a Product detail page (PDP) or a home page).

    • For a product listing page, open a product listing category.

  5. In the network monitoring tool, under the Name column, select the latest request to the Search API. The request path should contain /rest/search/v2.

  6. Select the Response tab.

  7. Find the searchHub field, and ensure that the value is expected and follows the naming convention.

    search hub value in a Search API response | Coveo

  8. Considering that you followed the recommended condition-based query routing mechanism, the query should be routed to the expected query pipeline since the pipeline has a condition based on the value of the search hub. Still in the Response tab, find the pipeline field, and validate that the query is routed to the right query pipeline.

    pipeline value in a Search API response | Coveo

To validate the search hub value in requests to Coveo UA

In requests to Coveo UA, the value of the search hub that was defined at the interface level and in the authentication method appears in the originLevel1 field of the payload.

  1. Access the interface for which you want to validate the value of the originLevel1 field.

  2. Open your web browser’s developer tools.

    Note

    The examples in this article use the Google Chrome developer tools. For browser-specific information, see:

  3. Select the Network tab.

  4. Depending on whether you’re inspecting a search or click event, look for the following:

    • For a search event, under the Name column, you should see a request whose path contains /rest/ua/v15/analytics/search.

    • For a click event, under the Name column, you should see a request whose path contains /rest/ua/v15/analytics/click.

  5. Open the Payload tab.

  6. Check the value of the originLevel1 field. This value should match the searchHub value of the associated request to the Search API.

    origin level 1 value in a UA request | Coveo