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 button1 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.
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:
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> <!-- ... --> <!-- Coveo In-Product Experience --> <script type="text/javascript" src="SCRIPT_URL" async ></script> <!-- End Coveo In-Product Experience --> <!-- ... --> </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.
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:
-
Enter a suitable Pipeline name (e.g.,
MySpeedbitIPX_Main
). -
(Recommended) Select or create a Condition. Use
Search Hub is SEARCH_HUB
, where you replaceSEARCH_HUB
with the actual search hub value used for your IPX interface (e.g.,MySpeedbitIPX
).
-
-
Click Add 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.
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.
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:
-
Enter a suitable Pipeline name (e.g.,
MySpeedbitIPX_Recommendation
). -
(Recommended) Select or create a Condition. Use
Search Hub is SEARCH_HUB AND Recommendation is Recommendation
, where you replaceSEARCH_HUB
with the actual search hub value used by IPX interface (e.g.,MySpeedbitIPX
).
-
-
Click Add 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.
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.
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.
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.
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 (whereTOKEN
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 aPipelineContext
component using the Interface Editor. -
Once the
CoveoInProduct
global variable is available, set the custom context as needed by invoking thesetContextValue
and/orsetContext
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.