Sending Custom Context Information

Coveo JavaScript Search Framework (September 2016)

The Coveo JavaScript Search Framework provides various ways of including custom context information in the search requests and Coveo Usage Analytics (Coveo UA) events originating from a search interface.

Custom context information can serve several purposes in a Coveo-powered solution:

The PipelineContext component is specifically designed to inject custom context information into search requests and Coveo UA events.

When using this component, you can set the custom context to send statically (i.e., in the component markup configuration), and dynamically (i.e., by invoking methods on the initialized component instance).

Setting Custom Context Statically

If some, or all, of the custom context information you want to send is meant to remain static after the page has been served, you can set it as JSON in the markup configuration of the PipelineContext component. Custom context values set in this fashion must be strings or arrays of strings.

<div id="search" class="CoveoSearchInterface">
  <!--  ...  -->
  <script class="CoveoPipelineContext" type="text/context">
    {
      "ageGroup": "30-45",
      "interests": ["sports", "camping", "electronics"]
    }
  </script>
  <!--  ...  -->
</div>

When using certain versions of the Interface Editor to modify the code of a hosted search page, configuring a PipelineContext component as shown in the example above may not work.

In such a situation, configure your PipelineContext through the UI View rather than the Code View to ensure that the required character encoding is generated.

Setting Custom Context Dynamically

If some, or all, of the custom context information you want to send may change dynamically (e.g., based on actions taken by the end user), you can set it as needed by invoking the setContextValue or setContext methods on the initialized PipelineContext component instance. Custom context values set in this fashion must be strings or arrays of strings.

The methods described in this section are available since the December 2017 Release (v2.3679.4) of the JavaScript Search Framework.

To set custom context dynamically with prior versions of the framework, you must use a buildingQuery event handler.

Consider the following search interface markup configuration:

<div id="search" class="CoveoSearchInterface">
  <!--  ...  -->
  <script class="CoveoPipelineContext" type="text/context"></script>
  <!--  ...  -->
</div>

Suppose the following functions are available to retrieve contextual information about the current end user:

/**
 * @returns {String}: The age group to which the current user belongs.
 * E.g., "30-45"
 */
function getUserAgeGroup() { /* Implementation... */ }
 
/**
 * @returns {String[]}: The interest categories for the current user.
 * E.g., ["sports", "camping", "electronics"]
 */
function getUserInterests() { /* Implementation... */ }

You can use the setContextValue method of the PipelineContext component to include this contextual information in search requests and usage analytics events.

// ...
const root = Coveo.$$(document).find("#search");
// ...
Coveo.$$(root).on("afterInitialization", (e, args) => {
  let pipelineContext = Coveo.$$(root).find(".CoveoPipelineContext");
  pipelineContext = Coveo.get(pipelineContext);
  pipelineContext.setContextValue("ageGroup", getUserAgeGroup());
  pipelineContext.setContextValue("interests", getUserInterests());
})
// ...
Coveo.init(root);

Alternatively, you can use the setContext method to set multiple context key-values at once.

pipelineContext.setContext({
  "ageGroup": getUserAgeGroup(),
  "interests": getUserInterests()
});

Using a buildingQuery Event Handler

Since the December 2017 Release (v2.3679.4) of the JavaScript Search Framework, it is recommended that you use the PipelineContext component instead of a buildingQuery event handler to send custom context information.

You can use a buildingQuery event handler to dynamically set context information (see JavaScript Search Framework Events). Custom context values set in this fashion can be of any type, although using strings and arrays of strings is generally recommended.

// ...
const root = Coveo.$$(document).find("#search");
// ...
Coveo.$$(root).on("buildingQuery", (e, args) => {
  args.queryBuilder.addContext({
    "userAgeGroup": "30-45",
    "userInterests": ["sports", "camping", "electronics"]
  })
})
// ...
Coveo.init(root);
Recommended Articles