Coveo In-Product Experience (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 Cloud 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.

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. If this is what you want to do, contact Coveo Sales.

Deploying an IPX Interface (Overview)

Assuming you have access to a Coveo Cloud 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:

  1. Create your IPX interface.

  2. 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

  1. On the In-Product Experiences page, click Add In-Product Experience.

  2. In the Configuration tab, fill the Basic settings section.

  3. (Optional) Use the Design and Content access tabs to customize your IPX interface.

  4. Click Save.

    Creating an IPX interface - 1

  5. 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.

    Creating an IPX interface - 2

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.

  1. 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.

  2. On the In-Product Experiences page, retrieve the script URL of the IPX interface you want to add to your web site or application.

    Retrieving the script URL for an IPX interface

  3. 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.

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.

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’ll 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

  1. On the Query Pipelines page, click Add Pipeline.

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

  3. 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

  1. On the Models page, click the Add Model drop-down menu, and then select Add model.

  2. Enter a meaningful display Name for the model.

  3. Under Model type, select Automatic Relevance Tuning, and then click Next.

  4. Click Add Model.

  5. Repeat the above steps, this time selecting Query Suggestions as a Model type.

Creating an ART model

Assuming enough usage analytics data is available in your organization, the Coveo Cloud 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

  1. Access the Machine Learning tab of the main query pipeline you created for your IPX interface.

  2. In the Machine Learning tab, click Associate model.

  3. In the Associate a Machine Learning Model dialog that appears, in the Model drop-down menu, select the ART model you previously created.

  4. Click Associate Model.

  5. 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

  1. On the Query Pipelines page, click Add Pipeline.

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

  3. 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

  1. On the Models page, click the Add Model drop-down menu, and then select Add model.

  2. Enter a meaningful display Name for the model.

  3. Under Model type, select Event Recommendations, and then click Next.

  4. Click Next.

  5. Click Add Model.

Creating an ER model

Assuming enough usage analytics data is available in your organization, the Coveo Cloud 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

  1. Access the Machine Learning tab of the recommendation query pipeline you created for your IPX interface.

  2. In the Machine Learning tab, click Associate model.

  3. In the Associate a Machine Learning Model dialog that appears, in the Model drop-down menu, select the ER model you previously created.

  4. 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.

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.

  1. In your IPX’s configuration page, select the Design tab.

  2. In the Main button section, modify the settings as desired, and then click Save.

    Modifying the main button of an IPX interface

The changes take effect immediately.

Modifying the Search Panel (Advanced)

  1. In your IPX’s configuration page, select the Design tab.

  2. In the Search Panel section, click Use the interface editor.

    Modifying the search panel of an IPX interface - 1

  3. In the Interface Editor window, select the Code view tab.

  4. Modify the search panel markup configuration as desired, and then click Save.

    Modifying the search panel of an IPX interface - 2

The changes take effect immediately.

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.

  1. In the configuration page for your IPX interface, select the Content access tab.

  2. In the Default settings section, modify the settings as desired, and then click Save.

    Modifying the content access settings for an IPX interface

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. The actual implementation details will thus 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:

  1. Authenticate the user.

  2. Call a service exposed through the Coveo Cloud 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"
    }
  ]
}

  3. 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 -->

  4. 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:

  1. 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.

  2. 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>

Deleting an IPX

  1. 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.

  2. On the In-Product Experiences page, click the IPX interface you want to delete.

  3. In the Action bar, click Delete, and then click Delete again.

    Deleting an IPX interface

The IPX interface is immediately and irreversibly deleted.

Recommended Articles