Add a simple hosted search page to a website

This is for:

Developer

You can add a hosted search page to any of your websites and software-as-a-service (SaaS) applications.

When you create a search page with the search page builder, the page configuration automatically includes a dedicated JavaScript loader snippet script. You can use the loader snippet to embed the search page 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 search page.

To add a hosted search page to a website

  1. Configure search token authentication.

  2. Use the loader snippet to add the hosted search page to a website.

Configure search token authentication

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

  • Generic API key authentication: Use this simple configuration method to use the same generic search token to authenticate all users in your hosted search page. This token grants access to publicly available content only. This means that search page 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.

  • Advanced search token authentication: Use this configuration method if you want to generate a distinct search token for each authenticated user in your hosted search page 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.

Generic API key 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 search page. This means that search page 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.

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

If you created multiple search pages, each page 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 search page 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 search page. This configuration method is used if some or all of your indexed content is secured by a repository’s permissions system, and you want search page 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 a hosted search page to a website

This section describes how to add a hosted search page built with Coveo’s search page builder to a website.

Notes

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

  • A search page script is loaded asynchronously and uses about three kilobytes of memory.

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

  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 search page.

    Examples

    • If your Coveo organization’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 snippet for your search page.

  4. In the snippet 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 search page, and then save the completed script.

      Example

      Your search page loader snippet is:

      <script async onload="CoveoSearchPage.initialize('API_KEY')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/searchpage/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="CoveoSearchPage.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/searchpage/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 search page, where you replace LOADER_SNIPPET with your complete search page loader snippet 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 Search Page -->
   <LOADER_SNIPPET>
   <!-- End Coveo Search Page -->
   <!-- ... -->
</head>
<body>
   <!-- ... -->
</body>
</html>
    Example

    If your loader snippet script is:

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

    The snippet would be:

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

  6. Access the web page where you added the search page to ensure that it appears as intended.

Add custom context

To provide more personalized and relevant search results, you can set your search page 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 a search page, you must create a JSON object in your source code that contains the data, and then call the object when initializing the search page using the CoveoSearchPage.initialize function. The context that’s passed when the search page 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 CoveoSearchPage.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 search page, 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 the page in which you added the search page, pass the custom context when loading the search page using the following CoveoSearchPage.initialize function, where you replace CONTEXT with your JSON object.

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

    If your original search page loader script is <script async onload="CoveoSearchPage.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11')" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/searchpage/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 Search Page -->
   <script async onload="CoveoSearchPage.initialize('xx1xx11x1x-1x11-1111-x1x1-11x111111x11', myContext)" src="https://platform.cloud.coveo.com/rest/organizations/barcaorganization/searchpage/v1/interfaces/94218b9b-0a3e-4379-9dd4-ae3f4cbd2c80/loader"></script>
   <!-- End Coveo Search Page -->
   <!-- ... -->
</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 search page by using the CoveoSearchPage.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 = () => {
    CoveoSearchPage.addContext({
        app: {
            menuItem: "searchPages"
        }
    });
}

    • To add context based on an error:

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

  4. If you haven’t done so already, configure query pipelines and Coveo Machine Learning for your search page. 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.