Deploy Content Recommendations (CR)

This is for:

In this article

Complete Atomic code sample
What’s next?

The output of a Coveo Machine Learning (Coveo ML) Content Recommendation (CR) model depends on the history of recent user actions and recorded Coveo Usage Analytics (Coveo UA) search, click, and view events (see About Content Recommendations).

More data provides better recommendations, so you should start sending view events to Coveo UA as soon as possible.

Example

In a technical documentation site, you could add a recommendation interface to complement the table of contents and suggest articles which are frequently viewed by other users with similar session navigation history. A Recommended Articles component is rendered at the bottom of each article (including this one) on docs.coveo.com.

Optionally, plan the types of content to recommend:

A CR model can be configured to only learn from events that pertain to one or several specific types of content. Unless you want to create a model that outputs generic recommendations, you should plan ahead.

Example

You want to design Recommended Articles and Recommended Courses interfaces.

You determine that the Recommended Articles interface should only take the KBArticle content type into account. The Recommended Courses interface should take the TrainingVideo or InteractiveTutorial content types into account.
Optionally, plan the contextual user information to leverage:

You can determine what contextual user information is relevant to your use case, and send this data along with each UA event and query to allow your CR model to further personalize its output.

Example

You want the output of your recommendation interfaces to be tailored to the products owned by the end user.

You determine that you should leverage this contextual user information.
Get an access token:

You need an access token which grants limited privileges to:
- Allow tracked pages to send view events to feed your CR models.
- Allow your recommendation interfaces to send queries to get recommendations, and send search and click events for reporting purposes.
Depending on your use case, you can use either:
- A public API key that only grants the Analytics Data - Push and Execute Queries - Allowed privileges in your Coveo organization.
- A search token.
Send UA events:
1. Send view events.
  
  Start sending view events as soon as possible on the web pages which correspond to the indexed items that you want to be able to recommend.
2. Send search and click events.
  
  CR models can also learn from search and click events that originate from other search interfaces which are configured against the same Coveo organization. Ensure that all of your search pages are properly configured to send standard UA events.

Create a Coveo ML CR model and associate it with a CR-dedicated query pipeline.

Leading practices

Use a query pipeline dedicated to CR models to ensure that other search optimization features, such as Automatic Relevance Tuning (ART) or query ranking expressions (QREs), don’t interfere with their output.
When you want to power distinct recommendation interfaces (for example, Recommended Technical Articles, Recommended Experts, and Recommended Courses), configure a separate model for each planned interface. Associate them all with the same CR-dedicated query pipeline and add a specific condition to each model.

Don’t use the Default query pipeline for your CR model. Otherwise, all of the search interfaces that route their queries to the Default pipeline will break.

In the Coveo Administration Console, access your CR-dedicated query pipeline. If you don’t have one yet, you can create one.
Create a CR model.
Associate the CR model with your query pipeline, optionally with a condition.

Include a recommendation interface in your web pages.

You can use any of the Coveo search UI libraries to create a recommendation interface:
You could also configure a Recommendations widget in a ServiceNow service portal.

Complete Atomic code sample

Track views

You can use code similar to the following to send a view event when a web page is loaded. This piece of code can be added to every webpage that has been created using Atomic components.

<html lang="en"> 
  <head>
    <title>Page Title</title> 
    <script type="text/javascript"
            src="https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js"> 
    </script>
    <script>
      coveoua("init", "<ACCESS_TOKEN>", "<ANALYTICS_ENDPOINT>"); 
      coveoua("send", "view", { 
        contentIdKey: "@clickableuri", 
        contentIdValue: "window.location.href" 
        // ... Additional custom context information ...
      });
    </script>
    <!-- ... -->
  </head>
<!-- ... -->
</html>

	Sets the `language` metadata for view events sent from this page.
	Sets the `title` metadata for view events sent from this page.
	Imports the Coveo UA library to send view events and record actions history.
	`<ACCESS_TOKEN>`: A public API key that’s only granted the privileges to execute queries and push UA data in the target Coveo organization, or a valid search token if the page requires user authentication (see Search Token Authentication, Execute Queries Domain, and Analytics Data Domain). `<ANALYTICS_ENDPOINT>`: An organization analytics endpoint.
	Sends the view event with required and optional metadata key-value pairs.
	The name of a field that can be used to uniquely and permanently identify the tracked page as an item in the index (see About fields).
	The value of the field set in `contentIdKey` for the current tracked page.

Note

You can also install the Coveo UA library as an NPM package and reference it as an ESM module in your code.

Create a recommendation interface

To display recommendations, you have to create a recommendation interface and initialize it.

<!DOCTYPE html>
<html>
  <head>
    <title>Atomic Recommendation Interface</title>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css"/>
    <script type="module">
      (async () => {
          await customElements.whenDefined('atomic-recs-interface');
          const recommendInterface = document.querySelector('#recs');

          await recommendInterface.initialize({ 
              accessToken:'<ACCESS_TOKEN>',
              organizationId: '<ORGANIZATION_ID>'
          });

          recommendInterface.getRecommendations(); 
      })();
    </script>
  </head>
  <body>
    <atomic-recs-interface id="recs"> 
        <atomic-recs-list label="List of Recommendations" recommendation="recommendations"> 
            <atomic-recs-result-template> 
                <template>
                    <atomic-result-section-title>
                        <atomic-result-link></atomic-result-link>
                    </atomic-result-section-title>
                </template>
            </atomic-recs-result-template>
        </atomic-recs-list>
    </atomic-recs-interface>
  </body>
</html>

	The `initialize` method initializes the interface using the overarching `atomic-recs-interface` component. In this case, use the `await` operator to wait for the initialization to complete before moving on.
	The `getRecommendations` method retrieves recommendations after the interface is initialized.
	The `atomic-recs-interface` component is the parent of all of the other Atomic components in a recommendation interface. It must be initialized to enable recommendations.
	`atomics-recs-list` displays recommendations by applying the templates provided to it. Here, we provide a `label` for the recommendations along with a `recommendation` identifier used by Coveo ML to scope the recommendation interface.
	The `template` component defines the format of the query results. You need to place this component within `atomic-recs-result-template`.

What’s next?

For an overview of the core Atomic concepts used in the example above, see Content recommendations.