Leverage user context for Coveo Machine Learning

This is for:

Developer System Administrator

In this article

Requirements
Available options
JavaScript library

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 Platform 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).

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 rendering before the Coveo Page View Analytics component.

Available options

This section covers Coveo User Context rendering options, 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.

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 Enable context pipeline 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.

Custom context

The Custom context 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();