Add an in-product experience to a website

This is for:

System Administrator Developer

You can add a Coveo In-Product Experience (IPX) search interface to any of your enterprise web pages and software-as-a-service (SaaS) applications.

When you create an IPX interface, the IPX configuration automatically includes a dedicated JavaScript loader snippet script. You can use the loader snippet to embed the IPX search interface into a web page or an application.

Note

If you haven’t done so already, we strongly recommend that you configure query pipelines and Coveo Machine Learning for your IPX.

To add an IPX interface to a website

  1. Configure search token authentication.

  2. Use your IPX loader snippet to add the IPX interface to a website.

Note

By default, the IPX search interface uses the latest version of Coveo’s Atomic library. If you add IPX to a web page that contains another search interface that uses a different version of Atomic, IPX uses your search interface’s version of Atomic to avoid conflicts. As a result, some IPX components may not function as intended.

In this case, you can choose to isolate or sandbox the IPX search interface in an iframe so that each version of Atomic works independently without conflicts. However, using an iframe adds complexity to your implementation and requires a higher level of proficiency.

Configure search token authentication

You can configure search token authentication for your IPX search interface using one of the following two methods:

  • Generic search token authentication: Use this simple configuration method to use the same generic search token to authenticate all users in your IPX search interface. This token grants access to publicly available content only. This means that IPX users will only have access to indexed content that’s accessible to everyone, and indexed content that’s secured via a repository’s permissions system won’t appear in search results in IPX.

  • Advanced search token authentication: Use this configuration method if you want to generate a distinct search token for each authenticated user in your IPX search interface so that each user only sees the secured content that they’re allowed to access. Implementing advanced search token authentication requires you to add server-side logic to your website or application.

Note

For a classic IPX interface, see Add a classic IPX interface to a website. Classic IPX interface configurations appear with a Classic badge on the In-Product Experiences (platform-ca | platform-eu | platform-au) page.

Classic badge

Generic search token authentication

This authentication method requires you to create an API key that’ll be used as the generic search token to authenticate all users of your IPX search interface. This means that IPX users will only have access to indexed content that’s accessible to everyone, while indexed content that’s secured via a repository’s permissions system won’t appear in search results in IPX.

The API key is used to authenticate your IPX interface to execute queries in the Coveo Search API and send Coveo Usage Analytics (Coveo UA) events to Coveo.

If you created multiple IPX interfaces, each IPX interface requires its own API key.

Create an API key while making sure to grant the key only the following permissions:

Important

When Your API Key dialog appears, click Copy to copy the key value to your clipboard and paste the value to a safe location. This is the only time the key value will appear, so make sure to copy it when it appears. You’ll need the value when adding your IPX interface to your website or application.

Advanced search token authentication

Advanced search token authentication requires you to add server-side logic to your website or application for the purpose of generating a distinct search token for each authenticated user in your IPX search interface. This configuration method is used if some or all of your indexed content is secured by a repository’s permissions system, and you want IPX users to only see the secured content that they’re allowed to access.

This procedure outlined in this section is a general guideline as the actual implementation details vary from one project to another.

Note

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

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

  1. Authenticate the user in your website or application.

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

Add an IPX interface to a website

This section describes how to add an IPX interface to a website.

Notes

  1. If you haven’t done so already, configure search token authentication for your IPX interface.

  2. Ensure that the domain of your Coveo organization’s primary deployment region is allowlisted in the website or application in which you want to add the IPX interface.

    Examples

    • If your Coveo organizations’s deployment region is US East, allowlist platform.cloud.coveo.com.

    • If your Coveo organization is on the Coveo HIPAA platform, allowlist platformhipaa.cloud.coveo.com.

  3. Retrieve the loader script for your IPX interface.

  4. In the IPX loader script you just copied, complete the script by replacing API_KEY with one of the following depending on your chosen search token authentication method:

    • For generic search token authentication, replace API_KEY with the value of the API key that you created for your IPX, and then save the completed script.

      Example

      Your IPX loader snippet script is:

      <script async onload="CoveoIPX.initialize('API_KEY')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>

      Your API key value is xx1xx11x1x-1x11-1111-x1x1-11x111111x11.

      Your completed script is therefore:

      <script async onload="CoveoIPX.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>

    • For advanced search token authentication, you’ll need to programmatically inject a generated search token value into API_KEY. The details will depend on your specific implementation.

  5. Include a snippet similar to what follows in the <head> of each page in which you want to add the IPX interface, where you replace LOADER_SNIPPET with your complete IPX loader snippet script that includes your API key value (generic search token authentication) or your logic to generate and set search token values (advanced search token authentication):

    <!DOCTYPE html>
<html>
<head>
   <!-- ... -->
   <!--  Coveo In-Product Experience -->
   <LOADER_SNIPPET>
   <!-- End Coveo In-Product Experience -->
   <!-- ... -->
</head>
<body>
   <!-- ... -->
</body>
</html>
    Example

    If your IPX loader snippet script is:

    <script async onload="CoveoIPX.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>`

    The snippet would be:

    <!DOCTYPE html>
<html>
<head>
   <!-- ... -->
   <!--  Coveo In-Product Experience -->
   <script async onload="CoveoIPX.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>
   <!-- End Coveo In-Product Experience -->
   <!-- ... -->
</head>
<body>
   <!-- ... -->
</body>
</html>

  6. Access the web pages where you added the IPX interface to ensure that it appears as intended.

    If you configured your IPX to use the IPX button (see Set IPX placement), and the IPX interface or button is hidden behind another element on your web page, you must adjust the z-value of your IPX interface and button. To do so, add the following in the <head> of the page, where you replace Z_VALUE with a z-index value that’s greater than the z-index value of the element that’s covering the IPX interface or button:

    <style>
    coveo-ipx::part(atomic-ipx-modal) {
      z-index: Z_VALUE;
    }
    coveo-ipx::part(ipx-button) {
      z-index: Z_VALUE;
    }
</style>
    Example

    Your IPX interface and button are hidden behind an element on your web page that has a z-index value of 2000. Assign a z-index value for the IPX interface and button that’s greater than 2000, such as 2001, by adding the following in the <head> of the web page:

    <style>
    coveo-ipx::part(atomic-ipx-modal) {
      z-index: 2001;
    }
    coveo-ipx::part(ipx-button) {
      z-index: 2001;
    }
</style>

Add custom context

To provide more personalized and relevant search results, you can set your IPX search interface to send custom context data along with each user query.

You can then leverage the data in query ranking expressions (QREs) and query pipeline conditions to increase the relevance of search results. See Manage ranking expression rules and Manage query pipeline conditions for details on these features.

The data can also help to train Coveo ML models to boost results based on the context.

To include custom context in a search request that originates from an IPX search interface, you must create a JSON object in your source code that contains the data, and then call the object when initializing the IPX search interface using the CoveoIPX.initialize function. The context that’s passed when the IPX search interface initializes should be static data, such as an authenticated user ID or role.

If the custom context that you want to send is dynamic, such as context based on user action, you can use the CoveoIPX.addContext function after initialization to add or overwrite the context you set in the JSON object.

To add custom context:

  1. In the source code of the web page or application where you added the IPX interface, create a JSON object that contains the custom context to send.

    Note

    Coveo recommends that your JSON object minimally contains user and app context.
    Example

    In this example, we created a myContext JSON object that contains the custom context.

    const myContext = {
  "user": {
    "email": "user@company.com"
  },
  "app": {
   "title": "Home page"
  },
  "custom": {  }
}

  2. In the <head> of each page in which you added the IPX interface, pass the custom context when loading the IPX interface using the following CoveoIPX.initialize function, where you replace CONTEXT with your JSON object.

    CoveoIPX.initialize('API_KEY', <CONTEXT>)
    Example

    If your original IPX loader script is <script async onload="CoveoIPX.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>, and your JSON object is myContext, the modified script is the following:

    <!DOCTYPE html>
<html>
<head>
   <!-- ... -->
   <!--  Coveo In-Product Experience -->
   <script async onload="CoveoIPX.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11', myContext)" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/ipxinterface/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>
   <!-- End Coveo In-Product Experience -->
   <!-- ... -->
</head>
<body>
   <!-- ... -->
</body>
</html>

  3. If required, you can add additional context or overwrite context that you set in the JSON object after initializing the IPX search interface by using the CoveoIPX.addContext function. This is useful when you want to send dynamic context, such as context based on an error code or a click event related to a user action.

    Examples

    • To add context based on a click event:

      searchPagesMenu.onclick = () => {
    CoveoIPX.addContext({
        app: {
            menuItem: "searchPages"
        }
    });
}

    • To add context based on an error:

      errorHandler = (error) => {
    console.error("An error occurred", error);
    CoveoIPX.addContext({
        app: { errorCode: error.code }
    });
}

  4. If you haven’t done so already, configure query pipelines and Coveo Machine Learning for your IPX. You can leverage the custom context data in query ranking expressions (QREs) and query pipeline conditions to personalize and increase the relevance of search results.

    Note

    Use dot-walking syntax (for example, user.email) when referencing a context key in a query pipeline condition Context object.

Reset the IPX interface

Use the CoveoIPX.reset function to reset the IPX interface after it initializes. This is used primarily to reload the recommendations that appear in the IPX interface based on new context.

When using a Content Recommendation (CR) model with IPX, the list of recommendations is based on the context, such as view events and custom context, at the time when IPX loads (initializes) on the web page or application.

Coveo IPX recommendations

By default, the list of recommendations doesn’t change until the IPX interface reloads, no matter what actions are performed by the user. Moreover, when a user performs a search in IPX, the recommendation list is replaced by a search results list, and recommendations don’t appear again until the IPX interface reloads.

By resetting the IPX interface after it initializes, the recommendations re-appear and are based on the new context (view events and custom events) at the time of the reset. You can reset an IPX interface whenever your specific workflow requires. For example, you can reset the IPX interface when a user navigates to a different section in a single-page application (SPA).

When IPX resets, the IPX interface closes and then reloads the new recommendations list when a user opens the IPX interface.

Note

If your IPX interface is configured to appear in a custom element on your webpage, the IPX’s current state (open/closed) is maintained, and the new recommendations are loaded immediately. This means that it refreshes with the new recommendations if the IPX interface is open.

To reset an IPX interface

In the source code of the web page or application where you added the IPX interface, simply call the CoveoIPX.reset function when needed.

Add a classic IPX interface to a website

This section details how to add a classic IPX interface to a website.

Note

Classic IPX interface configurations appear with a Classic badge on the In-Product Experiences (platform-ca | platform-eu | platform-au) page.

Classic badge

Coveo supports existing classic IPX interfaces, but you can no longer create new IPX search interfaces using the classic configuration (see Create an IPX interface). However, you can still edit an existing classic IPX interface.

If your IPX interface isn’t a classic configuration, see Add an IPX interface to a website.
Show/hide instructions
Notes

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

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

  1. Ensure that the domain of your Coveo organization’s primary deployment region is allowlisted in the website or application in which you want to add the IPX interface.

    Examples

    • If your Coveo organizations’s deployment region is US-east, allowlist platform.cloud.coveo.com.

    • If your Coveo organization’s deployment region is Ireland, allowlist platform-eu.cloud.coveo.com.

    • If your Coveo organization is on the Coveo HIPAA platform, allowlist platformhipaa.cloud.coveo.com.

  2. Retrieve the loader snippet for the IPX interface from the Configuration tab of the IPX settings.

  3. Include a snippet similar to what follows in the <head> of each page in which you want to add the IPX interface, where you replace SCRIPT_URL with your IPX interface script URL (for example, https://platform.cloud.coveo.com/rest/organizations/barcaorganization/pages/abc8ccfe-bf50-42e7-a140-475420cbc543/inappwidget/loader):

    <!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>

Test an IPX interface

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 web page:

Note

This template is for next-gen IPX search interfaces that were created using the IPX simple builder. Use the classic template for classic IPX interfaces.

 
// ==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>';
    script.onload = () => {CoveoIPX.initialize('<API_KEY>')};
    document.head.appendChild(script);
})();

Replace <YOUR_SITE_NAME> with the name of your hosting site, <IPX_SCRIPT_REFERENCE> with your script URL, and <API_KEY> with the value of your API key value (generic search token authentication) or your generated search token (advanced search token authentication).

Template for classic IPX interfaces 
// ==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.