Manage Coveo In-Product Experiences (IPX)

The Coveo In-Product Experience (IPX) feature provides a quick and easy way to deploy and maintain feature-rich, lightweight Coveo search interfaces within your web sites or applications.

You can create and manage IPX interfaces directly from the Coveo Administration Console. Each IPX interface has a unique URL and can be loaded in any web page in which you want it available.

By default, an IPX interface appears as a button¹ in the lower right corner of a page. Clicking the button opens a compact search panel. Both the button and search panel can be fully customized.

An IPX interface automatically records Coveo Usage Analytics (Coveo UA) events. This means you can generate reports to gain insight into the way end users are interacting with your IPX interfaces. This also means you can enhance IPX interfaces with Coveo Machine Learning (Coveo ML) capabilities.

IPX Demo

1: It’s possible to deploy an IPX interface inside a native component of your web site or application instead of attaching it to the default button.

Deploying an IPX Interface (Overview)

Assuming you have access to a Coveo organization with at least one source (preferably one whose content is accessible to everyone), you can use the IPX feature.

Deploying an IPX interface minimally involves the following steps:

Create your IPX interface.
Load your IPX interface in the desired web site or application.

Although not mandatory, it’s also strongly recommended to configure query pipelines for your IPX interface.

Optionally, you may also customize your IPX interface by modifying its main button and search panel, and configuring its content access.

Creating an IPX Interface

On the In-Product Experiences page, click Add In-Product Experience.
In the Configuration tab, fill the Basic settings section.
(Optional) Use the Design and Content access tabs to customize your IPX interface.
Click Save.
In the You’re all set panel that appears, you may click Copy to save the loader snippet for your IPX interface to your clipboard, and then click Close.

You can always retrieve the loader snippet later.

You’re now ready to load your IPX interface in the desired web site or application.

However, we recommend that you configure query pipelines for your IPX interface before.

Loading an IPX Interface

This procedure must be executed by a developer who is allowed to modify code in the target web site or application.

Ensure that the platform.cloud.coveo.com domain is allowlisted in the web site or application in which you want to add the IPX interface.
On the In-Product Experiences page, retrieve the script URL of the IPX interface you want to add to your web site or application.
Include a snippet similar to what follows in the head of each page in which you want the IPX interface available:
```
<!DOCTYPE html>
<html>
<head>
  
  
  <script type="text/javascript" src="SCRIPT_URL" async ></script>
  
  
</head>
<body>
  
</body>
</html>
```
Where you replace SCRIPT_URL with your actual IPX interface script URL (e.g., https://platform.cloud.coveo.com/rest/organizations/speedbit1a2b34d5e/pages/abc8ccfe-bf50-42e7-a140-475420cbc543/inappwidget/loader).

An IPX interface script is loaded asynchronously and uses about three kilobytes of memory.

The IPX interface should now appear and be functional when loading any of the target pages in a browser.

IPX Demo

If you have not done so already, we strongly recommend that you configure query pipelines for your IPX interface.

Optionally, you can also customize your IPX interface.

Configuring Query Pipelines for an IPX Interface (Recommended)

When you create an IPX interface, you must specify a search hub value. Among other things, this important parameter is useful for routing search requests to specific query pipelines.

A pipeline can be associated with one or more Coveo ML models. Pipelines may also contain custom relevance tuning rules (thesaurus, featured results, stop words, etc.), allowing you to modify incoming search requests as you see fit.

You will likely want to configure two dedicated pipelines for your IPX interface: one main pipeline to process manual search requests, and one recommendation pipeline to take advantage of the Coveo ML Event Recommendations (ER) feature.

Step 1: Creating the Main Query Pipeline

On the Query Pipelines page, click Add Pipeline.
In the Configuration tab:
1. Enter a suitable Pipeline name (e.g., MySpeedbitIPX_Main).
2. (Recommended) Select or create a Condition. Use Search Hub is SEARCH_HUB, where you replace SEARCH_HUB with the actual search hub value used for your IPX interface (e.g., MySpeedbitIPX).
Click Add Pipeline.

Creating the main pipeline

Assuming each pipeline in your organization (except the default one) has a unique condition based on a distinct search hub value, all manual search requests originating from your IPX interface will now be routed to your new pipeline.

Step 2: Enabling Coveo ML ART and QS

Enabling the Coveo ML Automatic Relevance Tuning (ART) and Query Suggestions (QS) features can significantly improve relevance for end users performing manual queries through your IPX interface.

Step 2A: Creating the ART and QS Models

On the Models page, in the upper-right corner, click Add Model to open the Add a Machine Learning Model panel.
In the Add a Machine Learning Model panel, under Name enter a meaningful display name for the model.
Under Model type, select Automatic Relevance Tuning, and then click Next.
Click Add Model.
Repeat the above steps, this time selecting Query Suggestions as a Model type.

Creating an ART model

Assuming that enough usage analytics data is available in your organization, the Coveo Platform will generate the models. Generating a model typically takes about 30 minutes, depending on the amount of data to process.

Step 2B: Associating the ART and QS Models

Access the Machine Learning tab of the main query pipeline you created for your IPX interface.
In the Machine Learning tab, click Associate model.
In the Associate a Machine Learning Model dialog that appears, in the Model drop-down menu, select the ART model you previously created.
Click Associate Model.
Repeat the above steps. This time, in the Model drop-down menu, select the QS model you created before.

Associating an ART model to the main pipeline

Assuming the platform was able to generate the models, and the main pipeline is properly configured, the Coveo ML ART and QS features should now be enabled in your IPX interface.

Step 3: Enabling Coveo ML ER

Enabling the Coveo ML Event Recommendations (ER) feature will allow your IPX interface to suggest content related to the page the end user is currently viewing.

Step 3A: Creating the Recommendation Query Pipeline

On the Query Pipelines page, click Add Pipeline.
In the Configuration tab:
1. Enter a suitable Pipeline name (e.g., MySpeedbitIPX_Recommendation).
2. (Recommended) Select or create a Condition. Use Search Hub is SEARCH_HUB AND Recommendation is Recommendation, where you replace SEARCH_HUB with the actual search hub value used by IPX interface (e.g., MySpeedbitIPX).
Click Add Pipeline.

Creating the recommendation pipeline

Assuming the recommendation pipeline’s configuration is adequate, no search request should be routed to this new pipeline at this point. You must first create and associate an ER model to the pipeline.

Step 3B: Creating the ER Model

On the Models page, in the upper-right corner, click Add Model to open the Add a Machine Learning Model panel.
In the Add a Machine Learning Model panel, under Name enter a meaningful display name for the model.
Under Model type, select Event Recommendations, and then click Next.
Click Next.
Click Add Model.

Creating an ER model

Assuming that enough usage analytics data is available in your organization, the Coveo Platform will generate the model. Generating a model typically takes about 30 minutes, depending on the amount of data to process.

Step 3C: Associating the ER Model

Access the Machine Learning tab of the recommendation query pipeline you created for your IPX interface.
In the Machine Learning tab, click Associate model.
In the Associate a Machine Learning Model dialog that appears, in the Model drop-down menu, select the ER model you previously created.
Click Associate Model.

Associating an ER model to the recommendation pipeline

Assuming the platform was able to generate the ER model, and the recommendation pipeline is properly configured, the Coveo ML ER feature should now be enabled in your IPX interface.

Step 4: Defining Custom Relevance Tuning Rules (Advanced)

If needed, you can define custom relevance tuning rules in the configuration page of the main query pipeline you have created for your IPX interface.

Use the following table as a reference:

Rule type	Use case
Thesaurus	Defines synonyms to expand in user queries.
Featured results	Provides a high ranking score boost to certain items.
Stop words	Defines terms to ignore in the basic query expression (`q`).
Ranking expressions	Increases or decreases the ranking scores of certain items by a certain amount.
Ranking weights	Fine-tunes the default weights of the standard index ranking factors.
Triggers	Defines actions to execute in the search panel under certain circumstances.
Filters	Appends expressions to the basic (`q`), advanced (`aq`), constant (`cq`), disjunction (`dq`), or large (`lq`) query expression.
Query parameters	Sets or overrides the values of certain search request parameters.

Use custom relevance tuning rules sparingly and only for legitimate reasons.
Apply your custom relevance tuning rules conditionally.
Test your custom relevance tuning rules.

Customizing an IPX Interface

Modifying the Main Button

This procedure must be executed by a developer who knows how to use the JavaScript Search Framework.

In your IPX’s configuration page, select the Design tab.
In the Main button section, modify the settings as desired, and then click Save.

The changes take effect immediately.

Deploying an IPX Inside a Native Component (Advanced)

To deploy an IPX interface inside a native component of your web site or application instead of attaching it to the default button, you can use the Target selector section.

The Target selector section lets you replace the default IPX button by a custom open/close mechanism integrated within your web site or application.

In your IPX’s configuration page, select the Design tab.
In the Target selector box, enter a CSS selector to the element that should replace the default IPX button (e.g., #myElementId).
Click Save.

screen capture of the target selector section in the Coveo Administration Console

Modifying the Search Panel (Advanced)

You can use the Interface Editor in the Administration Console to customize the search panel.

In your IPX’s configuration page, select the Design tab.
In the Search Panel section, click Use the interface editor.
In the Interface Editor window, select the Code view tab.
Modify the search panel markup configuration as desired, and then click Save.

The changes take effect immediately.

To fully customize the look and functionality of an IPX, Coveo also provides an IPX starter project. You can use this project to edit the HTML, CSS, and JavaScript of an IPX, and then push that code to the Coveo Platform so that your IPX can use it. You can even have multiple IPX interfaces, each independently managed through version control.

Configuring Content Access (Advanced)

By default, an IPX interface uses the same generic search token to authenticate all users. This token is meant to grant access to publicly available content only. You can modify the information to include in it directly through the Administration Console.

If you would rather use a distinct search token for each authenticated user, enabling them to access the secured content they’re allowed to view in your IPX interface, you must implement advanced search token authentication.

Option 1: Modifying the Default Content Access Settings

Follow this procedure only if you want to modify the information to include in the search token that gets generated by default for all users of an IPX interface.

If you want each end user to be able to access the secured content they’re allowed to view in your IPX interface, you must instead implement advanced search token authentication.

In the configuration page for your IPX interface, select the Content access tab.
In the Default settings section, modify the settings as desired, and then click Save.

The changes take effect immediately.

Option 2: Implementing Advanced Search Token Authentication

This procedure must be executed by a developer who is allowed to modify code in the target web site or application.

Implementing advanced search token authentication requires you to add server-side logic to your web site or application. Therefore, the actual implementation details will vary from one project to another. This procedure only provides generic guidelines.

In summary, you must write server-side code that performs the following actions:

Authenticate the user.

Call a service exposed through the Coveo Platform to request a search token for the authenticated user.

POST https://platform.cloud.coveo.com/rest/search/token HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

{
  "userIds": [
    {
      "name": "asmith@example.com",
      "provider": "Email Security Provider"
    }
  ]
}

In the snippet for the IPX interface to load, inject the access_token=TOKEN query parameter into the script URL (where TOKEN must be replaced by the actual search token that was generated for the authenticated user).

<!--  Coveo In-Product Experience -->
<script type="text/javascript" src="https://platform.cloud.coveo.com/rest/organizations/speedbit1a2b34d5e/pages/abc8ccfe-bf50-42e7-a140-475420cbc543/inappwidget/loader?access_token=eyJhbGciOiJIUzI1NiJ9.eyJ2OCI6dHJ1ZSwib3JnYW5pemF0aW9uIjoic3BlZWRiaXQxYTJiMzRkNWUiLCJ1c2VySWRzIjpbeyJwcm92aWRlciI6IkVtYWlsIFNlY3VyaXR5IFByb3ZpZGVyIiwibmFtZSI6ImFzbWl0aEBleGFtcGxlLmNvbSIsInR5cGUiOiJVc2VyIn1dLCJyb2xlcyI6WyJxdWVyeUV4ZWN1dG9yIl0sImV4cCI6MTU3OTgwMzcxNSwiaWF0IjoxNTc5NzE3MzE1fQ.aPFX20a7IdvtKuw89len98fDqMbSo87ER7isSCn-Q90" async ></script>
<!-- End Coveo In-Product Experience -->

Serve the page, including the snippet in its head.

For more information and examples, see Search Token Authentication.

Passing Custom Context (Advanced)

This procedure must be executed by a developer who knows how to use the JavaScript Search Framework.

Passing custom context through an IPX interface helps train Coveo ML models to provide more relevant results to users (see Understanding Custom Context).

To do so:

Ensure that your IPX interface contains a PipelineContext component.

A PipelineContext component is included by default in all IPX interfaces created after March 10th, 2020. For older IPX interfaces, you can add a PipelineContext component using the Interface Editor.
Once the CoveoInProduct global variable is available, set the custom context as needed by invoking the setContextValue and/or setContext methods.

You want to collect information from the registered users on the Speedbit Dashboard (i.e., their subscription level, age group, and which Speedbit products they already own) to better provide suggestions as to what they may need next.

Assuming you have implemented the getSubscriptionLevel, getAgeGroup, and getOwnedProducts functions to retrieve the target values, you can use them to pass custom context as follows:

<head>
   <!-- ... -->
   <!--  Pass custom context to IPX  -->
   <script>
      // Wait for IPX interface to load...
      window.addEventListener('load', () => {
         CoveoInProduct.setContext({
            "subscriptionLevel": getSubscriptionLevel(),
            "ageGroup": getAgeGroup(),
            "ownedProducts": getOwnedProducts()
         });
      });
 
      function getSubscriptionLevel() { /* Implementation here... */ }
      function getAgeGroup() { /* Implementation here... */ }
      function getOwnedProducts() { /* Implementation here... */ }
 
   </script>
   <!-- End pass custom context to IPX -->
   <!-- ... -->
</head>

Testing an IPX with JavaScript Injection

You can use script injection tools to test your IPX on your hosting domain. This is particularly useful when running a demo and investigating where this integration would make the most sense. For example, using Tampermonkey, you can fill in and use the following template to inject your IPX into a page:

// ==UserScript==
// @name         IPX Demo Template
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  Coveo In-Product Experience
// @author       you@name.com
// @match        <YOUR_SITE_NAME>
// @grant        none
// @noframes
// ==/UserScript==
(function() {
    'use strict';
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.src = '<IPX_SCRIPT_REFERENCE>';
    document.getElementsByTagName('head')[0].appendChild(script);
})();

Replace <YOUR_SITE_NAME> with the name of your hosting site, and <IPX_SCRIPT_REFERENCE> with your script URL.

Deleting an IPX

Ensure that the loader snippet for the IPX interface you want to delete is no longer included in any page of your web site or application. Otherwise, the console will display a 404 error when the browser attempts to load the script.
On the In-Product Experiences page, click the IPX interface you want to delete.
In the Action bar, click Delete, and then click Delete again.

The IPX interface is immediately and irreversibly deleted.

Supported Browsers

An IPX interface must be accessed from a browser that supports Web Components.