--- title: Send custom context information slug: '399' canonical_url: https://docs.coveo.com/en/399/ collection: javascript-search-framework source_format: adoc --- # Send custom context information [jsui-new Coveo JavaScript Search Framework v1.1276.18] The [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) provides various ways of including custom [context](https://docs.coveo.com/en/1345/) information in the search requests and [Coveo Analytics](https://docs.coveo.com/en/182/) [events](https://docs.coveo.com/en/260/) originating from a [search interface](https://docs.coveo.com/en/2741/). Custom context information can serve several purposes in a Coveo implementation: * You can use it to create custom [dimensions](https://docs.coveo.com/en/258/) for your Coveo Analytics [reports](https://docs.coveo.com/en/266/) (see [Manage dimensions on custom metadata](https://docs.coveo.com/en/1522/)). * [Coveo Machine Learning](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) can take advantage of it to promote contextually relevant content (see [About custom context](https://docs.coveo.com/en/3389/)). * You can reference it in [query ranking expressions (QREs)](https://docs.coveo.com/en/1472/) and [query pipeline conditions](https://docs.coveo.com/en/2793/) (see [Manage ranking expression rules](https://docs.coveo.com/en/3375/) and [Manage query pipeline conditions](https://docs.coveo.com/en/1959/)). > **Notes** > > * In fact, you can inject the value of a custom context key into any query expression. > * If you're using Coveo for Salesforce, the methods described in this section apply to Salesforce Classic. > To learn how to add custom context information in Salesforce Lightning, see [Send context information in Salesforce Lightning](https://docs.coveo.com/en/3290#adding-context-with-custom-code). ## Using the PipelineContext component (recommended) The [`PipelineContext`](https://coveo.github.io/search-ui/components/pipelinecontext.html) component is specifically designed to inject custom context information into search requests and Coveo UA search events. When using this component, you can set the custom context to send [statically](#setting-custom-context-statically) (that is, in the component markup configuration), and [dynamically](#setting-custom-context-dynamically) (that is, 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. ```html

``` To send the same custom context info along with click and custom events, use a `changeAnalyticsCustomData` event handler (see [Modify the metadata to send with Coveo Analytics events](https://docs.coveo.com/en/365#modify-the-metadata-to-send-with-coveo-analytics-events)). ```html

``` > **Note** > > When using certain versions of the Interface Editor to modify the code of a legacy [hosted search page](https://docs.coveo.com/en/2866/), configuring a `PipelineContext` component as shown in the example above may not work. > > In such a situation, configure your `PipelineContext` through the [**UI View**](https://docs.coveo.com/en/1852#ui-view) rather than the [**Code View**](https://docs.coveo.com/en/1852#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 (for example, based on actions taken by the end user), you can set it as needed by invoking the [`setContextValue`](https://coveo.github.io/search-ui/components/pipelinecontext.html#setcontextvalue) or [`setContext`](https://coveo.github.io/search-ui/components/pipelinecontext.html#setcontext) methods on the initialized `PipelineContext` component instance. Custom context values set in this fashion can be strings or maps of strings. > **Note** > > The methods described in this section are available since the [December 2017 release (v2.3679.4)](https://docs.coveo.com/en/373#december-2017-release-v236794) of the JavaScript Search Framework. > To set custom context dynamically with prior versions of the framework, you must [use a `buildingQuery` event handler](#using-a-buildingquery-event-handler). Consider the following search interface markup configuration: ```html

``` Suppose the following functions are available to retrieve contextual information about the current end user: ```javascript /** * @returns {String}: The age group to which the current user belongs. * For example, "30-45" */ function getUserAgeGroup() { /* Implementation... */ } /** * @returns {Map}: The interests selected by the current user. * For example, { "0": "sports", "1": "camping", "2": "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. ```javascript // ... 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. ```javascript pipelineContext.setContext({ "ageGroup": getUserAgeGroup(), "interests": getUserInterests() }); ``` To send the same custom context info along with click and custom events, use a `changeAnalyticsCustomData` event handler (see [Modify the metadata to send with Coveo Analytics events](https://docs.coveo.com/en/365#modify-the-metadata-to-send-with-coveo-analytics-events)). ```html

``` ## Using a buildingQuery event handler > **Leading practice** > > Since the [December 2017 release (v2.3679.4)](https://docs.coveo.com/en/373#december-2017-release-v236794) of the JavaScript Search Framework, [use the `PipelineContext` component](#using-the-pipelinecontext-component-recommended) instead of a `buildingQuery` event handler to send custom context information. You can use a [`buildingQuery`](https://coveo.github.io/search-ui/classes/queryevents.html#buildingquery) event handler to dynamically set context information (see [JavaScript Search Framework Events](https://docs.coveo.com/en/417/)). ```javascript // ... const root = Coveo.$$(document).find("#search"); // ... Coveo.$$(root).on("buildingQuery", (e, args) => { args.queryBuilder.addContext({ "ageGroup": "30-45", "interests": { "0": "sports", "1": "camping", "2": "electronics" } }) }) // ... Coveo.init(root); ``` To send the same custom context info along with click and custom events, use a `changeAnalyticsCustomData` event handler (see [Modify the metadata to send with UA events](https://docs.coveo.com/en/365#modify-the-metadata-to-send-with-coveo-analytics-events)). ```html

``` > **Note** > > In the samples above, the `interests` context is passed as an object that simulates an array. > > To access a specific element within such an "array" in a query expression, you would pass something like `$context.interests.1`