Implementation Guide

Build a Search UI Coveo Relevance Cloud Developer Product Documentation

Regardless of the approach you choose to build your Coveo-powered search interface, follow the implementation guidelines in this article.

These guidelines apply to any website, regardless of the Content Management System (CMS) you use. By default, the search interfaces you create will display items from all your Coveo organization sources in the search results.

The following diagram gives a high-level view of the server-side tasks you need to code to build a functional search interface. The diagram also shows the client-side event flow before the search page is ready for use. More details about specific pieces of the implementation are provided further below.

General guidelines when building a search interface in a website

To link a search interface to your Coveo organization, configuration is required. You want to store the configuration parameters in your CMS. Minimally, these should include the following:

The Platform Endpoint URL

Coveo exposes base Coveo API endpoints that are data residency region-specific (e.g., https://platform-eu.cloud.coveo.com). Store the base platform endpoint associated with your data residency region in your CMS.

For multi-region deployments, contact Coveo Sales to have a dedicated Coveo Search API endpoint set up for you.

The Coveo Organization ID

Calls to the Coveo Search API require that you specify your organization ID. This information may be found in the Coveo Administration Console, on the Settings (platform-ca | platform-eu | platform-au) page, under Organization > Details.

The Search Hub

The search hub is an important piece of information that your search interface should send to the Search API in its queries. When creating your Search API key, you will limit the scope of the key to this search hub.

The Search API Key

On the API Keys (platform-ca | platform-eu | platform-au) page, create an API key and, in the Privileges tab, grant the following privileges:

Service Domain Access level

Analytics

Analytics data

Push

Search

Execute queries

Allowed

Search

Impersonate

Allowed
Important

To follow leading security practices, you need to limit the scope of your search API key to a given search hub. The Add key button is inactive until a search hub is selected.

Limiting the API key scope

The Search API key will be used to generate a search token.

Warning

Never expose a Search API key in client-side code.

Retrieve the User Context

You need to retrieve the user context to generate a search token for the corresponding security identity in your Coveo organization.

Generate a Search Token

Your server-side code will use the Search API key from your configuration storage and the security identity to request a search token for that user (see Sample Usage Workflow).

To get the full URL for your search token POST call, append /rest/search/v2/token to your Platform Endpoint URL. For example, if your data residency region is Ireland, the full URL for your search token POST call is https://platform-eu.cloud.coveo.com/rest/search/v2/token.

Your Coveo search library client-side code will use the search token to authenticate requests to the Coveo Search API.

Warning

Never expose a Search API key in client-side code. The generated search token can be exposed as it’s scoped to the current user context.

Search token authentication is only one of several methods you can use to authenticate calls to the Coveo REST API.

Serve the Coveo-Powered Search Page

You need to write your search page HTML and JavaScript sections, following the reference documentation of the search interface library you chose to use.

Tip

The Coveo Atomic library is the recommended approach to building your Coveo-powered search pages in websites. See the following resources to build an Atomic search page:
EXAMPLE

You have decided to use Coveo Atomic as your search interface library. You can use your stored and generated constants as follows:

Search Token and Coveo organization ID: Use these values in the searchInterface initialize method, for the accessToken and organizationId arguments respectively. If your Coveo organization isn’t in the US East region, also provide the platformUrl argument in the initialize method, as in the following example:

<script>
  (async () => {
    await customElements.whenDefined("atomic-search-interface");
    const searchInterface = document.querySelector("#search");

    await searchInterface.initialize({
      accessToken: "eyJhbGciOiJIUzI1NiJ9eyM2OCI6dHJ1ZSwib3JnYW5pemF0aW9uIjoibWR0ZXN0MjIyc2VySWRzIm92a...",
      organizationId: "mtest211p9s2x",
      platformUrl: "https://platform-eu.cloud.coveo.com"
    });
    searchInterface.executeFirstSearch();
  })();
</script>

Search Hub: Use this value for the atomic-search-interface component searchHub property.

When the Search Interface Is Ready for Use

Once initialized, the search interface listens and reacts to events on its components. For example, if you type a query in the search box and then click on its submit button, the search interface component will call the Coveo Search API using the search token. The Search API response will be a list of results.

By default, the atomic-search-interface component automatically sends UA events to the region-specific analytics endpoint along with every search call.

With the JavaScript Search Framework, you need to add the Analytics component to record search interface UA events.

Be aware that the atomic-search-interface component reflectStateInUrl property default value is true. This setting appends the basic query expression (q) to your search page URLs as a URI fragment and may conflict with web server configurations.