Use a hosted page in your infrastructure

This is for:

Developer

In this article

Install the components
Use atomic-simple-builder
Use atomic-hosted-page

If your Atomic search page is hosted on Coveo infrastructure, you can use a component to consume it from anywhere on the web.

For search pages listed in the Simple Builder & Classic Interface Editor tab of the Search Pages (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you will use the atomic-simple-builder component. For search pages listed in the Custom Deployment tab, you will use the atomic-hosted-page component.

These components leverage the Hosted Page API to retrieve the hosted content and insert it into the target web page.

Install the components

Both components are published together as the atomic-hosted-page web component. You can install them by including a CDN link or using NPM.

CDN

The simplest way to get the component is through a content delivery network (CDN).

Include the following script in the target HTML page:

<script
    type="module"
    src="https://static.cloud.coveo.com/atomic-hosted-page/v0/atomic-hosted-page/atomic-hosted-page.esm.js">
</script>

NPM

The atomic-hosted-page component is also available as an npm package:

npm install @coveo/atomic-hosted-page

All of the resources will be available under /node_modules/@coveo/atomic-hosted-page/dist/atomic-hosted-page. You can include these in target pages with <script> tags.

If you’re using a module bundler (Browserify, Webpack, Rollup, etc.), you can use require('@coveo/atomic-hosted-page') or import '@coveo/atomic-hosted-page'.

Use `atomic-simple-builder`

If you used the Simple builder to create and customize your Atomic search page, then it will be listed in the Simple Builder & Classic Interface Editor tab of the Search Pages (platform-ca | platform-eu | platform-au) page of the Administration Console. You can use the atomic-simple-builder component to consume it from anywhere on the web.

Initialize `atomic-simple-builder`

Once you have installed the atomic-hosted-page web component, you’ll need to add a script like the following to initialize the atomic-simple-builder component:

<head>
  <!-- ... -->
  <script>
    (async () => {
      await customElements.whenDefined('atomic-simple-builder');
      const builder = document.querySelector('atomic-simple-builder');

      await builder.initialize({
        accessToken: '<ACCESS_TOKEN>', 
        organizationId: '<ORGANIZATION_ID>', 
        organizationEndpoints: await builder.getOrganizationEndpoints('<ORGANIZATION_ID>'),
        interfaceId: '<INTERFACE_ID>' 
      });
    })();
  </script>
  <!-- ... -->
  <atomic-simple-builder></atomic-simple-builder>
  <!-- ... -->
</head>

	`<ACCESS_TOKEN>` (string) is an API key or search token that grants the View all access level on the Search Pages domain in the target Coveo organization.
	`<ORGANIZATION_ID>` (string) is the unique identifier of your organization (e.g., `mycoveoorganizationa1b23c`).
	`<INTERFACE_ID>` (string) is the unique identifier of the hosted page, which you can copy from the Search Pages (platform-ca \| platform-eu \| platform-au) page of the Administration Console.

An API key with this access level will give access to the HTML, CSS, and JavaScript code for every search page in your organization. Make sure that you follow all client-side development best practices, and don’t put sensitive information in your search page code.

On initialization, the component performs the following actions:

Retrieve the hosted page configuration.
Insert the contents of the HTML parameter as innerHTML.
Insert the contents of each JavaScript parameter as a script tag in the header of the page.
Insert the contents of each CSS parameter as a link tag in the header of the page.

Leverage `atomic-simple-builder`

Custom <atomic-simple-builder> elements will surround the search interface in the main HTML file, which is located at src/pages/index.html. The atomic-simple-builder component uses these elements as delimiters. It will parse, upload, and insert the HTML within them into your infrastructure.

Use `atomic-hosted-page`

If you customized your Atomic search page locally and deployed it to the Coveo infrastructure, then it will be listed in the Custom Deployment tab of the Search Pages (platform-ca | platform-eu | platform-au) page of the Administration Console. You can use the atomic-hosted-page component to consume it from anywhere on the web.

Initialize `atomic-hosted-page`

Once you have installed the atomic-hosted-page web component, you’ll need to add a script like the following to initialize the atomic-hosted-page component:

<head>
  <!-- ... -->
  <script>
    (async () => {
      await customElements.whenDefined('atomic-hosted-page');
      const page = document.querySelector('atomic-hosted-page');

      await page.initialize({
        accessToken: '<ACCESS_TOKEN>', 
        organizationId: '<ORGANIZATION_ID>', 
        organizationEndpoints: await page.getOrganizationEndpoints('<ORGANIZATION_ID>'),
        pageId: '<PAGE_ID>' 
      });
    })();
  </script>
  <!-- ... -->
  <atomic-hosted-page></atomic-hosted-page>
  <!-- ... -->
</head>

	`<ACCESS_TOKEN>` (string) is an API key or search token that grants the View all access level on the Search Pages domain in the target Coveo organization.
	`<ORGANIZATION_ID>` (string) is the unique identifier of your organization (e.g., `mycoveoorganizationa1b23c`).
	`<PAGE_ID>` (string) is the unique identifier of the hosted page, which you can copy from the Administration Console.

On initialization, the component performs the following actions:

Retrieve the hosted page configuration.
Insert the contents of the HTML parameter as innerHTML.
Insert the contents of each JavaScript parameter as a script tag in the header of the page.
Insert the contents of each CSS parameter as a link tag in the header of the page.

Leverage `atomic-hosted-page`

Regardless of how you generated your Atomic search page, custom <atomic-hosted-page> elements will surround the search interface in the main HTML file, which is located at src/pages/index.html. The atomic-hosted-page component uses these elements as delimiters. It will parse, upload, and insert the HTML within them into your infrastructure.

If you deployed your own Atomic project to the Coveo infrastructure, make sure to enclose the search interface HTML within <atomic-hosted-page> elements so that you can leverage the web component.