Create and manage Coveo In-Product Experiences (IPX)

Coveo In-Product Experience (IPX) is a lightweight and feature-rich Coveo search interface that you can quickly add to any of your websites and software-as-a-service (SaaS) applications.

The compact search interface is customizable and provides users with access to relevant content directly from your web pages.

IPX Demo

An IPX search interface automatically records Coveo Usage Analytics (Coveo UA) events. This lets you enhance the relevance of search results in your IPX search interfaces using Coveo Machine Learning (Coveo ML). Usage analytics events also let you generate reports to gain insight on how users are interacting with your IPX interfaces.

Typically, website users access the IPX search interface via a button on the web page. But you can configure your IPX interface so that it appears in a custom element on your website. Both the IPX button and IPX search interface is customizable.

Deploy an IPX interface (Overview)

To successfully deploy an IPX interface, you must meet the following minimum requirements and configuration.

Requirements

A Coveo organization with at least one source (preferably a source with content that’s accessible to everyone).

Important

By default, the IPX search interface doesn’t authenticate users. This means that IPX users will only have access to indexed content that’s accessible to everyone. Indexed content that’s secured via a repository’s permissions system won’t appear in search results in IPX as users can’t be authenticated.

If you need to authenticate users so that IPX users only see the items that they’re allowed to access, you must create a classic IPX interface, which allows for advanced search token authentication. IPX interfaces created using the new IPX simple builder don’t support user authentication. However, Coveo strongly recommends that you use the IPX simple builder to create your IPX interface, instead of creating 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.

Create an IPX interface

This section details how to create the new (next-gen) IPX interface using the IPX simple builder.

Note

The next-gen IPX search interface, which is created using the simple builder, leverages Coveo’s latest Headless and Atomic libraries.

The previous IPX search interface, which is based on the Coveo JavaScript Search Framework, is now referred to as the classic IPX interface. Although the classic IPX interface is still available, Coveo strongly recommends that you use the simple builder to create your IPX interfaces.

The classic IPX interface should only be used when your IPX implementation requires specific advanced configuration and you’re instructed to by Coveo personnel. For instructions on how to create and customize a classic IPX interface, see Create and customize a classic IPX interface.

  1. On the In-Product Experiences (platform-ca | platform-eu | platform-au) page, click Add in-product experience.

  2. Click Simple builder.

  3. Enter a descriptive Name for your IPX configuration.

    Important

    The name that you choose for your IPX configuration will also be used as the search hub value for your IPX interface. The search hub value is the identifier for your IPX interface that’s used for query pipeline routing, usage analytics reporting, and enabling Coveo Machine Learning features. The IPX name and search hub value can’t be modified once the IPX configuration is created.

  4. Click Add. The IPX builder opens.

    Note

    You may be required to log in to the builder using the credentials you used to log in to the Coveo Administration Console.

  5. Customize your IPX interface.

Customize an IPX interface

This section details how to customize an IPX search interface using the IPX simple builder.

Note

For instructions on how to create and customize a classic IPX interface, see Create and customize a classic IPX interface.

From the IPX simple builder, you can:

Access the IPX builder

The IPX simple builder lets you customize an IPX search interface configuration. After you create an IPX interface, you can access its configuration settings at any time.

Note

To customize a classic IPX interface, see Create and customize a classic IPX interface.

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

  2. Click Edit in the Action bar.

    Note

    You may be required to log in to the builder using the credentials you used to log in to the Coveo Administration Console.

Live builder preview

The IPX simple builder includes a live preview that automatically updates based on the configuration options.

Besides showing you how your IPX interface looks, the preview is also fully interactive so you can perform actions such as searches, click search results, and open and close the IPX interface. Use the preview to see your IPX interface customizations and functionality in real time.

IPX preview

Manage result templates

Result templates set how individual query results appear in the search interface based on certain conditions. For example, you can display results for PDFs and web pages differently.

You can:

Result templates are evaluated in the order they appear in the Search results display tab. This means that if a query result meets the conditions found in multiple templates, the first applicable template in the list is used.

Create and edit result templates

  1. If required, access the IPX builder.

  2. Select the Search results display tab.

  3. Do one of the following:

    • To create a new template, click Add template.

    • Click the result template that you want to edit.

  4. Specify the template settings:

    • Enter a descriptive Name for your template.

    • Under Usage, set the condition(s) for when to use the template:

      1. Click Add condition to add a new condition, or click an existing condition that you want to edit.

      2. In the Select a field dropdown menu, select the desired field (e.g., source).

      3. In the Select a condition dropdown menu, select the desired operator (e.g., Must match).

      4. In the Values field, specify at least one value (e.g., YouTube).

        Tip
        Tip

        Use a comma-separated list to specify multiple values.

      5. Click Done to apply your changes.

    • Under Colored badge, select what’s displayed for the colored badge above the search result:

      1. Select a field to show its data in the badge.

        badge
      2. Select a color for the badge.

    • Under Additional information, set the information to display below the search result:

      1. Click Add details to add new information, or click the existing information that you want to edit.

      2. Select a field to display the corresponding metadata value.

        metadata
      3. (Optional) To include a label for the selected field, select the Include label checkbox, and then enter a custom label or keep the default field name.

      4. Click Done to apply your changes.

        Tip

        Change the order in which the information appears by clicking Template reorder icon to drag a details card to its new location in the list.

  5. Click Done to save the result template.

  6. Click Save at the upper-right of the builder to save your IPX interface.

Reorder result templates

Result templates are evaluated in the order they appear in the Search results display tab. This means that if a query result meets the conditions found in multiple templates, the first applicable template in the list is used.

Note

The Default template can’t be reordered.

  1. If required, access the IPX builder.

  2. Select the Search results display tab.

  3. In the Result templates section, click Template reorder icon on a template card to drag it to its new location in the list.

  4. Click Save at the upper-right of the builder to save your IPX interface.

Delete a result template

  1. If required, access the IPX builder.

  2. Select the Search results display tab.

  3. In the Result templates section, click the result template you want to delete.

  4. Click Delete.

  5. Click Delete again to confirm the action.

Manage facets

When facets are enabled, a Filters button appears at the top of the search interface.

IPX facet button

Clicking the Filters button shows the Filters screen where the configured facets appear as filter categories.

IPX facets
Note

By default, an IPX configuration includes the Source, Author, and Item Type facets.

You can:

Enable or disable facets

When facets are enabled, a Filters button appears at the top of the search interface that, when clicked, shows the Filters screen with the configured facets.

IPX facet button
Important
Important

All existing facets will be permanently deleted if you disable facets and then click Save at the upper-right of the builder to save your IPX interface.

  1. If required, access the IPX builder.

  2. Select the Filtering options tab.

  3. To enable or disable all facets, click On or Off respectively in the Facets section.

  4. Click Save at the upper-right of the builder to save your IPX interface.

Create and edit facets

  1. If required, access the IPX builder.

  2. Select the Filtering options tab.

  3. Do one of the following:

    • To create a new facet, click Add facet.

    • Click the facet that you want to edit.

  4. Specify the facet settings:

    • Select the Field to use for the facet (e.g., year or itemtype).

    • Enter the Name to display for the facet in the search interface.

    • Depending on the selected field, a Display section may appear. If so, select whether to display the facet options As checkboxes or As links.

  5. Click Done to apply your changes.

  6. Click Save at the upper-right of the builder to save your IPX interface.

Delete a facet

  1. If required, access the IPX builder.

  2. Select the Filtering options tab.

  3. Click the facet that you want to delete.

  4. Click the Trash icon button.

  5. Click the Trash icon button again to confirm.

  6. Click Save at the upper-right of the builder to save your IPX interface.

Manage tabs

When enabled, tabs appear at the top of the IPX search interface. Each tab shows a subset of items based on the tab configuration.

IPX tabs
Note

By default, an IPX configuration includes an All tab that can’t be deleted to ensure that all content can be viewed.

You can:

Enable or disable tabs

Important
Important

All existing tabs will be permanently deleted if you disable tabs and then click Save at the upper-right of the builder to save your IPX interface.

  1. If required, access the IPX builder.

  2. Click the Filtering options tab.

  3. To enable or disable all tabs, click On or Off respectively in the Facets section.

    Note

    The All tab can’t be deleted and is provided by default to ensure that all content can be viewed.

  4. Click Save at the upper-right of the builder to save your IPX interface.

Create and edit tabs

  1. If required, access the IPX builder.

  2. Click the Filtering options tab.

  3. Do one of the following:

    • To create a new tab, click Add tab.

    • Click the tab that you want to edit.

  4. Specify the tab settings:

    • In the Label field, enter the name that will be displayed on the tab in the search interface.

    • Under Usage:

      1. Click Add condition to add a new condition for what will appear in the tab.

      2. In the Select a field dropdown menu, select the desired field (e.g., source).

      3. In the Select a condition dropdown menu, select the desired operator (e.g., Must match).

      4. In the Values field, specify at least one value (e.g., YouTube).

        Tip
        Tip

        To specify multiple values, use a comma to separate each value.

      5. Click Done to apply your changes.

  5. Click Done to save the tab.

  6. Click Save at the upper-right of the builder to save your IPX interface.

Reorder tabs

Note

The All tab can’t be reordered. It always appears first as it displays all content.

  1. If required, access the IPX builder.

  2. Click the Filtering options tab.

  3. In the Tabs section, click Template reorder icon on a tab card to drag it to its new location in the list.

  4. Click Save at the upper-right of the builder to save your IPX interface.

Delete a tab

  1. If required, access the IPX builder.

  2. Select the Filtering options tab.

  3. Click the tab that you want to delete.

    Note

    The All tab can’t be deleted.

  4. Click Delete.

  5. Click Delete again to confirm.

  6. Click Save at the upper-right of the builder to save your IPX interface.

Set interface colors and text

You can customize the colors and text of your IPX search interface as desired or to match the website or application in which you’ll add the IPX interface.

  1. If required, access the IPX builder.

  2. Select the UI configuration tab.

  3. Under Theme, select the Primary, Secondary, and Background colors for the search interface.

  4. Under Text:

    • The Font family CSS property sets the prioritized list of supported generic and specific font families for your search interface. By default, the most common fonts are included in the list. The IPX interface will use the first font in the list that’s supported by your website. If required, modify the font-family list to match the website or application in which you’ll add the IPX interface.

      Note

      The builder’s live preview won’t display a font if it’s not a font that’s currently available in your web browser.

    • Select the Visited link color for the search interface.

    • For Title, select the color for headings and titles in the search interface.

  5. Click Save at the upper-right of the builder to save your IPX interface.

Set IPX placement

Typically, the IPX search interface opens and closes via a button on the web page where the IPX is added. The button and IPX interface appear at the bottom-right of the web page. But you can also configure your IPX interface so that it appears in a custom element on your website. Use the Placement section to set how to display the IPX search interface.

  1. If required, access the IPX builder.

  2. Select the UI configuration tab.

  3. Under Placement, select whether to use the IPX button or a custom element:

    • To use the IPX button:

      1. Select Open with a button.

      2. Select the Button color.

      3. In the Label field, enter the text what will appear on the button (e.g., Search).

      4. Select the Label color.

      5. (Optional) For Button icon, click Upload SVG image to select a custom image to use as the icon in the IPX button when the IPX search interface is closed. By default, a magnifying-glass icon appears.

    • To add the IPX search interface in a custom element:

      1. Select Show in a custom element.

      2. Enter a CSS selector to target the HTML element on your web page where you want your IPX interface to appear.

        Example

        Enter #sidepanel to target a div element on your website that has an ID of sidepanel.

  4. Click Save at the upper-right of the builder to save your IPX interface.

You can add a footer section to the IPX search interface where you can add links and logos.

You can:

Important
Important

All existing footer elements will be permanently deleted if you disable the footer and then click Save at the upper-right of the builder to save your IPX interface.

  1. If required, access the IPX builder.

  2. Select the UI configuration tab.

  3. To enable or disable the footer, click On or Off respectively in the Footer section.

  4. Click Save at the upper-right of the builder to save your IPX interface.

The footer can contain up to three text links and logos in any combination. A logo can also contain a link.

  1. If required, access the IPX builder.

  2. Click the UI configuration tab.

  3. If required, in the Footer section, click On to enable the footer.

    Important
    Important

    All existing footer elements will be permanently deleted if you disable the footer and then click Save at the upper-right of the builder to save your IPX interface.

  4. Do one of the following:

    • Click Add a link or logo to add a new footer element, and then click Link or Logo.

    • Click the footer element that you want to edit.

  5. Specify the settings:

    • For links:

      1. Enter a Link URL.

      2. Enter the Text to display.

    • For logo:

      1. Click Upload SVG image to select a custom image to add to the footer.

      2. (Optional) Enter a Link URL for the logo.

  6. Click Done to apply your changes.

  7. Click Save at the upper-right of the builder to save your IPX interface.

The footer area is separated into three distinct areas (left, center, right). Footer elements appear on the left, center, or right footer area based on the order that the elements appear in the Footer section. The top-most element appears in the left footer area and the lowest element appears in the right footer area. You can reorder your footer elements as desired.

  1. If required, access the IPX builder.

  2. Select the UI configuration tab.

  3. In the Footer section, click Template reorder icon on a footer element card to drag it to its new location in the list.

Enable or disable Smart Snippets

The IPX search interface supports Coveo Machine Learning (Coveo ML) Smart Snippets. Smart Snippets provide users with answers to their queries directly on the results page by displaying a snippet of the most relevant result item. For more information, see About Smart Snippets.

Important
Important

Enabling the Smart Snippets option allows Smart Snippets to appear in your IPX search interface, but only if you have a Smart Snippet model that’s associated with your IPX’s main query pipeline.

You can enable this option in advance even if you haven’t yet created a Smart Snippet model or associated it with your main query pipeline. However, without a properly configured Smart Snippet model, this option has no effect.

To configure a Smart Snippet model for use with IPX, see Configure query pipelines and machine learning for IPX.

To enable or disable Smart Snippets

  1. If required, access the IPX builder.

  2. Select the Settings tab.

  3. Select or clear the Smart Snippets checkbox to enable or disable the feature in IPX respectively.

Access the IPX search hub value and loader script

Your IPX interface configuration includes a dedicated search hub value and loader snippet script.

The search hub value is the identifier for your IPX interface that’s used for query pipeline routing and enabling Coveo Machine Learning features (see Configure query pipelines and machine learning for IPX). The search hub value is based on the name of your IPX configuration and can’t be modified.

The loader snippet script is required when adding your IPX interface to websites and applications.

To retrieve the search hub value or loader script

  1. If required, access the IPX builder.

  2. Select the Settings tab.

  3. In the Search hub or Loader snippet section, click clipboard icon to copy the search hub value or loader script respectively.

Delete an IPX

Important

Deleting an IPX search interface is irreversible.

  1. Ensure that the loader snippet for the IPX interface you want to delete is no longer included in any page of your website or application. Otherwise, the console will display a 404 error when the browser attempts to load the script.

  2. On the In-Product Experiences (platform-ca | platform-eu | platform-au) page, click the IPX interface you want to delete, and then click Delete in the Action bar.

  3. Click Delete to confirm.

Create and customize a classic IPX interface

This section details how to create and configure a classic IPX search interface.

Note

Coveo strongly recommends that you use the IPX simple builder to create the next-gen IPX interface, instead of creating 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.

IPX classic configuration

Create a classic IPX interface

  1. On the In-Product Experiences (platform-ca | platform-eu | platform-au) page, click Add in-product experience.

  2. Click Advanced deployment.

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

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

  5. Click Save.

    Creating an IPX interface - 1
  6. Before embedding the IPX interface into websites, we recommend that you Configure query pipelines for your IPX.

  7. In the Loader snippet panel that appears, you may click Copy to save the loader snippet for your IPX interface to your clipboard, and then click Save.

    Note

    You can always retrieve the loader snippet later.

    Creating an IPX interface - 2
  8. You’re now ready to embed your IPX interface in your website.

Modify the main button

Note

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

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

  2. In the Main button section, modify the settings as desired, and then click Save. The changes take effect immediately.

    Modifying the main button of an IPX interface

Advanced main button modification using CSS

For increased flexibility when embedding your IPX in websites and applications, you can use the following elements in the CSS of your web page to modify the style of the IPX button, the button icon, and the button text.

Note

Modifying the style attributes of the IPX button using the above CSS elements overrides the corresponding settings in the IPX configuration Design tab. For example, if you set the button color in the Design tab, and then specify a different color in the CSS, your IPX interface uses the color specified in the CSS of the corresponding web page.

  • coveo-in-app-widget-loader::part(button): Modifies the style of the IPX button.

  • coveo-in-app-widget-loader::part(button-text): Modifies the style of the text that appears in the IPX button.

  • coveo-in-app-widget-loader::part(button-icon): Modifies the style of the icon that appears in the IPX button.

In the CSS of your web page that includes your IPX interface, add one or more of the above elements within a style tag and specify the attributes as required using standard CSS rules.

Example

You want the IPX button width to adjust to the button text. You add the following style tag to your web page HTML:

<style> coveo-in-app-widget-loader::part(button) { width: inherit; } coveo-in-app-widget-loader::part(button-text) { max-width: unset; } </style>

Deploy IPX in a native component (advanced)

To deploy an IPX interface inside a native component of your website 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 website or application.

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

  2. In the Target selector box, enter a CSS selector to the element that should replace the default IPX button (e.g., #myElementId).

  3. Click Save.

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

Modify the search panel (advanced)

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

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

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 Coveo so that your IPX can use it. You can even have multiple IPX interfaces, each independently managed through version control.

Configure content access (advanced)

When embedding your IPX interface in websites and applications, the IPX interface uses the same generic search token to authenticate all users by default. This token is meant to grant access to publicly available content only. You can modify the information to include in the generic search token directly through the Administration Console.

If you would rather use a distinct search token for each authenticated user to provide access only to the secured content they’re allowed to view, you must instead implement advanced search token authentication.

Option 1: Modify the default content access settings

Note

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. On 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: Implement advanced search token authentication

Note

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

Implementing advanced search token authentication requires you to add server-side logic to your website 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:

  1. Authenticate the user.

  2. Call a service exposed through Coveo 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 with 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.

Pass custom context (advanced)

Note

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

Passing custom context through an IPX interface helps train Coveo ML models to provide more relevant results to users.

To do so:

  1. Ensure that your IPX interface contains a PipelineContext component.

    Note

    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.

Example

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>