Content recommendations

This is for:

Developer

In this article

Implement recommendations
Style your components
Display results
In a framework

The Coveo Atomic library provides a set of customizable UI components that can be used to leverage content recommendations powered by Coveo Machine Learning (Coveo ML). This article provides an overview of the core Atomic concepts needed to implement recommendations.

Note

CR models depend on view events and the user’s action history. To display recommendations with Atomic, you need to have configured a CR model and logged the required usage analytics events.

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 will 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 with an overarching atomic-search-interface component, recommendations require you to initialize the atomic-recs-interface component using 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 retrieves recommendations after the interface is initialized.

Atomic provides recommendations based on the history of actions that a user has taken on the webpage. It considers the URLs of the web pages they visit to provide recommendations from your indexed content. As a result, no recommendations will 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 want to provide custom context information, you can do so after you initialize your recommendation components. Custom context allows Coveo ML to favor 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 help you 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, if you have correctly set up your CR model, Coveo ML will favour content which matches the `support` context, or which 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.

Display 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’s no recommendation component that supports folding (that is, displaying results hierarchically).

To display result-specific information, use Result Template components.

In a framework

Recommendation components can be used out of the box in a Vue.js project.

To use recommendations in others frameworks such as React or Angular, the Atomic React wrapper and Atomic Angular wrapper expose the components described in this article. The only thing that changes is the name of the component during implementation, 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.