How To Setup Coveo Recommendations

Why Coveo Recommendations?

The beauty of using Coveo Recommendations is that they work both as part of a search result as well as integrating them on any page you may wish. The benefit is that you're going to be improving the experience for the end-user and in all likelihood, getting them to what they may be after, faster. It gives your site some smarts. So really, the question is why not use Coveo Recommendations?

Let's Add Recommendations To A Page

If you're using the JSUI, adding recommendations is broken up into two parts, the HTML and the JavaScript. If you're using Hive, it's as simple as adding the rendering to the page in Sitecore. For today, we're going to add it to the page manually.

The HTML

The HTML portion of Coveo Recommendations is a rather simple structure but offers a fair bit of customization if desired.

<div id="recommendation"
    class="CoveoRecommendation"
    data-results-per-page="5"
    data-pipeline="{coveo-recommendation-query-pipeline}">
    <div class="CoveoAnalytics" data-search-hub="{coveo-recommendation-search-hub}"></div>
    <div class="coveo-recommendation-header">
        <div class="coveo-recommendation-title">{coveo-recommendation-title}</div>
    </div>
    <div class="coveo-recommendation-body">
        <div class="CoveoResultList"></div>
    </div>
</div>

So what are all the variables, let's break it down.

coveo-recommendation-query-pipeline: This is not the query pipeline used for your search page. What the typical process is is to duplicate your existing query pipeline, (e.g. default -> default-recommendations). From there you will want to assign the appropriate Event Reommendation (EV) or Automatic Relevance Tuning (ART) model. The reason you will want to do this is because if you have specific boosts, or QRE's on your default query pipeline, you don't want those interfering with the Recommendation engine.

coveo-recommendation-search-hub: The Search Hub is essentially a tag that is added to all usage analytics with a reference to the search interface. An example value might be "MainRecommendations".

coveo-recommendation-title: It's just that, the title you want to appear above the recommended results.

And that's all you need to do to get basic Recommendations. If you want to extend the look and experience further, you'll notice a class we've covered before, CoveoResultList. And just like normal search results, you can customize these the same way. We'll dive into customizing Coveo Recommendations in a future article.

The JavaScript

The second half of getting recommendations to show is to have it initialized, which as you guessed it is via JavaScript. So let's get that setup.

// Import CSS and JS files
<link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.5395/css/CoveoFullSearch.css"/>
<script class="coveo-script" src="https://static.cloud.coveo.com/searchui/v2.5395/js/CoveoJsSearch.Lazy.min.js"></script>

<script>
document.addEventListener("DOMContentLoaded", () => {

    // Configure a search endpoint for the recommendation interface.
    Coveo.SearchEndpoint.configureCloudV2Endpoint("{org-id}", "{access-token}");

    // Initialize the recommendation interface.
    Coveo.initRecommendation(Coveo.$$(document).find("#recommendation"));
});
</script>

Let's look at the key points of information we need to make this work:

org-id: This is the organization ID you will find inside Platform Admin.

access-token: This value is what you'll need to setup as the API key for accessing Coveo Cloud. You will need your API token to have the ability to execute queries and push analytic data.

#recommendation: This selector matches the id attribute of the the div element with the CoveoRecommendation class name. You could use different selectors if so desired.

Extra Step For Integrating Within A Search Interface

The code above works great if you're embedding a recommendation list within a page, say along side an article. But what if you want to display the recommendations above search results inside a typical search page. For that to work, the JavaScript is a tad bit different.

<script>
document.addEventListener("DOMContentLoaded", () => {

    // Configure a search endpoint for the recommendation interface.
    Coveo.SearchEndpoint.configureCloudV2Endpoint("{org-id}", "{access-token}");

    // Initialize the recommendation interface and reference the encompassing search interface.
    const recommendationElem = Coveo.$$(document).find("#recommendation");
    const searchInterfaceElem = Coveo.$$(document).find("#search");
    Coveo.initRecommendation(recommendationElem,searchInterfaceElem);
});
</script>    

You'll see we identify both the recommendation element and the search interface element. From there we initialize the recommendation and associate it to the search interface.