Add an IPX interface to a website

Coveo In-Product Experience System Administrator Developer Product Documentation

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. Create an API key.

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

Tip

You can test your IPX interface before adding it your website.

Create an API key for IPX

If you created an IPX interface using the IPX simple builder, you must create an API key that’s 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.

Note

An API key is not required for classic IPX search interfaces. If you created a classic IPX interface, see Add a classic IPX interface to a website.

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.

Add an IPX interface to a website

This section describes how to add an IPX interface that was created with the simple builder. If you created a classic IPX interface, see Add a classic IPX interface to a website.

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.

  • You can test your IPX interface before adding it your website.

  1. If you haven’t done so already, create an API key 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’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.

  3. Retrieve the loader snippet for your IPX interface:

    1. On the In-Product Experiences (platform-ca | platform-eu | platform-au) page, click the IPX interface that you want to add.

    2. Click Copy to clipboard in the Action bar.

  4. In the IPX loader snippet script you just copied, complete the script by replacing API_KEY with the value of the API key that you created for your IPX, and then save the completed script.

    Example

    If 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>, and your API key value is xx1xx11x1x-1x11-1111-x1x1-11x111111x11, your completed 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>

  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 IPX loader snippet script that includes your API key value:

    <!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 a classic IPX interface to a website

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

Note

Coveo recommends that you use the IPX simple builder to create a next-gen IPX interface instead of using a classic IPX interface. The classic IPX interface should only be used when your IPX implementation requires specific advanced configuration and you’re instructed to by Coveo personnel.
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 script URL of the IPX interface:

    1. On the In-Product Experiences (platform-ca | platform-eu | platform-au) page, click the classic IPX interface that you want to add.

    2. Click Copy to clipboard in the Action bar.

  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 (e.g., 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 IPX API key.

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.