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 you host your Atomic search page on Coveo Platform infrastructure, you can use a component to consume it from any location on the web.

For Atomic search pages listed in the Simple Builder & Legacy Interface Editor tab of the Search Pages (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you’ll use the atomic-simple-builder component. For search pages listed in the Custom Deployment tab, you’ll 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.

Legacy search pages were created using the Coveo JavaScript Search Framework. They aren’t compatible with Atomic.

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 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 (such as Browserify, Webpack, or Rollup), 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 & Legacy 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’ve 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 platform token that grants the View all access level on the Search pages and IPX domain in the target Coveo organization.
	`<ORGANIZATION_ID>` (string) is the unique identifier of your organization (for example, `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 Platform 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’ve 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 platform token that grants the View all access level on the Search pages and IPX domain in the target Coveo organization.
	`<ORGANIZATION_ID>` (string) is the unique identifier of your organization (for example, `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 Platform infrastructure, make sure to enclose the search interface HTML within <atomic-hosted-page> elements so that you can leverage the web component.