Content Recommendations
Content Recommendations
The Coveo Atomic library provides a set of customizable UI components that can be used to leverage Content Recommendations (CR) powered by Coveo ML. This article provides an overview of the core Atomic concepts needed to implement recommendations.
To display recommendations with Atomic, you need to have previously configured a Content Recommendations ML Model and logged the required usage analytics events.
CR models depend heavilly on view events, typically logged using the coveoua.js script.
Implement Recommendations
Initialize Recommendations
Assemble the target Atomic recommendation components to display recommendations:
<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> |
The atomic-recs-interface component is the parent of all other atomic components in a recommendation interface and needs to be initialized to enable recommendations.
We’ll cover initialization below. |
|
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 format of the query results is defined by a template component that needs to placed within atomic-recs-result-template. |
Similar to how a search interface is initialized via an overarching atomic-search-interface component, recommendations require you to initialize the atomic-recs-interface component via a script:
<head>
<script>
(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> |
The initialize method initializes the interface.
In this case, use the await operator to wait for the interface initialization to complete before moving on. |
|
The getRecommendations method fetches recommendations after the interface initialization. |
|
Please note that Atomic provides recommendations based on the history of actions you have taken on the webpage. It considers the URL of the web pages you visit to provide recommendations from your indexed content. As a result, no recommendations may be returned to you during local development. |
A complete code example implementing recommendations can be found in the Atomic project repository.
Set Context
If you wish to provide custom context information, you can do so after you initialize your recommendation components. Custom context allows Coveo ML to favour content that matches or is accessed more in a specific context. This can lead to more personalized recommendations. Familiarizing yourself with how to access Headless through Atomic will allow you to better understand the example below, which showcases how to set the custom context.
<script>
import {loadContextActions} from '/build/headless/recommendation/headless.esm.js';
(async () => {
await customElements.whenDefined('atomic-recs-interface');
const recommendInterface = document.querySelector('#recs');
await recommendInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>'
});
const context = {
website: 'support',
};
const engine = recInterface.engine;
engine.dispatch(loadContextActions(engine).setContext(context));
recommendInterface.getRecommendations();
})();
</script> |
Define the context.
In this scenario, provided that you have correctly setup your CR model, Coveo ML will favour content matching the support context, or that is popular in that context, when fetching recommendations. |
|
Access and store the engine variable. |
|
Use the engine and the Headless action creator you imported above to create a setContext action creator.
Pass in the defined context and dispatch the action. |
Style Your Components
You can style recommendation components in the same manner as other Atomic components.
The following is an example of how you could style the label associated with the provided list of recommendations by accessing the shadow DOM part:
<style>
atomic-recs-list::part(label) {
padding-top: 4rem;
font-size: 1.125rem;
font-weight: 400;
}
</style>For a more detailed guide on how to customize your components, see Themes and Visual Customization.
Displaying Results
To display recommendation results, add a result list component.
Instead of using atomic-result-list, you can use atomic-recs-list and provide it with result templates to define how results are rendered.
This means that a template element must be the child of an atomic-recs-result-template, and an atomic-recs-list must be the parent of each atomic-recs-result-template.
Unlike regular search components, there is no recommendation component that supports folding (i.e., displaying results hierarchically).
To display result-specific information, use Result Template Components.
In a Framework
Recommendation components can used out of the box in a Vue.js project.
To utilize recommendations in others frameworks such as React or Angular, the Atomic React wrapper and the Atomic Angular wrapper expose the components described in this article. The only thing that changes is the name of the component during implementaion as shown in the Atomic React example below:
<AtomicRecsInterface engine={engine}>
<AtomicRecsList
numberOfRecommendations={3}
label="List of Recommendations"
template={(result) => (
<>
<p>
{"Title: "}
<AtomicResultLink></AtomicResultLink>
</p>
</>
)}
/>
</AtomicRecsInterface>A complete code example implementing recommendations in Atomic React can be found in the Atomic project repository.
Very useful
Not really
Very useful
Not really