Leverage user context for Coveo Machine Learning

This is for:

Developer System Administrator
Warning
Legacy feature

This article pertains to achieving relevance with the Coveo Hive framework. Coveo Hive is now in maintenance mode.

See Achieve relevance for guidance on leveraging Coveo relevance features with the Coveo Atomic library.

Enterprise edition

User context consists of many key-value pairs that are taken into account when searching results and getting content recommendations. This context is used by Coveo Machine Learning (Coveo ML) to boost results based on other users with a similar profile. You can have as many values in your context as needed and Coveo ML automatically adjusts to consider the most relevant ones (see About custom context).

Important

Non-alphanumeric context key characters are automatically translated to underscore characters.

Requirements

  • Configure your site to enable content recommendations (see Getting Content Recommendations).

  • Add the Coveo User Context component before the Coveo Page View component.

Available options

This section covers each option, when to use them and what to expect.

Component When to use it Possible effects

Anonymity

You want different content recommendations whether the user is logged in or not.

A logged in user will get more results visited by users that are logged in, while anonymous users will get more results visited by anonymous users.

Country

You want different content recommendations based on the user country.

A user from a certain country will get more results visited by other users from the same country.

Device

You want different content recommendations based on the user device.

A mobile user will get more results viewed by other mobile users.

Profile Cards

You want different content recommendations based on the user Sitecore profile card.

A user with a specific profile card will get more results viewed by other users of the same profile card.

UserContextPipeline

If the EnableContextPipeline property is enabled, the coveoUserContext pipeline is run to change properties in the user context. This pipeline is useful for more advanced logic when the other properties don’t provide enough flexibility.

Example

The following processor adds a static value to the user context.

using Coveo.Analytics.Pipelines;
using Coveo.Framework.Processor;

namespace MyNamespace
{
    public class MyProcessor : IProcessor<UserContextPipelineArgs>
    {
        public void Process(UserContextPipelineArgs p_Args)
        {
            p_Args.CurrentValues["NewKey"] = "MyValue";
        }
    }
}

In the Process method, add some code to add, change, or remove keys and values from the user context. The pipeline is run after all the other properties have been added, so you can conditionally remove options that were previously enabled in the parameters.

To use this processor, access the <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo\Coveo.SearchProvider.Custom.config file, and in the pipeline node, add the following:

<coveoUserContext>
   <processor type="MyNamespace.MyProcessor, MyAssembly" />
</coveoUserContext>

The processor args also provides the current Sitecore context in the p_Args.SitecoreContext property.

CustomContext

The CustomContext property lets you add a static context directly within the rendering parameters. It’s useful if you have different templates for different sections of your site and want a different context key for each section. For example, in a news website, you could set the section key with the news value for news articles, and blog for blog articles.

JavaScript library

It’s also possible to add context using a JavaScript object, for example, if you need to add information related to the client. The CoveoForSitecoreUserContext variable has a handler that can modify the context.

CoveoForSitecoreUserContext.handler.setContext("key", "value");

You can get the current context using the following method:

CoveoForSitecoreUserContext.handler.getContext();