About the search hub
About the search hub
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:
-
Enforce proper query routing
-
Avoid secured content leaks
-
Increase Coveo Machine Learning (Coveo ML) models relevance
-
Ensure accurate reporting
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
In requests to Coveo UA
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.
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.
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:
-
On a search interface, you must set the search hub value on the
atomic-search-interface
component. -
On a recommendation component, you must define the search hub on the
atomic-recs-interface
component.
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 |
Recommendation |
Set the search hub value using the |
Product Recommendation |
Set the search hub value using the |
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.
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.
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:
-
To learn how manage API keys, see Manage API keys.
-
To learn how to manage search tokens, see Use search token authentication.
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 |
|
A product listing page |
|
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 However, the identifier value of the recommendation component is used for reporting purposes.
Specifically, the Coveo UA service utilizes the 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 |
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.
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
-
Access the interface for which you want to validate the search hub and query pipeline value.
-
Open your web browser’s developer tools.
NoteThe examples in this article use the Google Chrome developer tools. For browser-specific information, see:
-
Select the Network tab.
-
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.
-
-
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
. -
Select the Response tab.
-
Find the
searchHub
field, and ensure that the value is expected and follows the naming convention. -
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.
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.
-
Access the interface for which you want to validate the value of the
originLevel1
field. -
Open your web browser’s developer tools.
NoteThe examples in this article use the Google Chrome developer tools. For browser-specific information, see:
-
Select the Network tab.
-
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
.
-
-
Open the Payload tab.
-
Check the value of the
originLevel1
field. This value should match thesearchHub
value of the associated request to the Search API.