Upgrade from v2 to v3
Upgrade from v2 to v3
This is for:
DeveloperThe Coveo Platform platform is constantly evolving. Atomic v3 introduces changes and innovations that align with the latest evolution of the Coveo Platform.
The following are breaking changes from Atomic v2 to v3
|
Migration to Coveo Event Protocol
Coveo Event Protocol becomes the new default protocol.
In other words, the Engine interface analytics.analyticsMode
default value is now next
rather than legacy
.
If you’re using the default value in V3 and aren’t ready to migrate to the new protocol, set the value to legacy
to keep using the Coveo UA protocol.
Only Coveo for Commerce supports EP at the moment.
For every other kind of implementation, set |
const searchInterface = document.querySelector('atomic-search-interface');
await searchInterface.initialize({
// ...
analytics: {analyticsMode: 'legacy'},
});
// ...
Organization endpoints
Organization endpoints is a feature that improves separation of concerns, resiliency, and makes multi-region and data residency deployments smoother. Starting with Atomic v3, the usage of organization endpoints will be enforced automatically, as opposed to being optional in v2.
Atomic Version 2
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>',
organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>'),
});
searchInterface.executeFirstSearch();
})();
Atomic Version 3
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>',
});
searchInterface.executeFirstSearch();
})();
For HIPAA organizations, rather than specifying hipaa
argument in the getOrganizationEndpoints
function, set the environment
property to hipaa
.
Atomic Version 2
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>',
organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>', 'hipaa'),
});
searchInterface.executeFirstSearch();
})();
Atomic Version 3
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>',
environment: 'hipaa',
});
searchInterface.executeFirstSearch();
})();
For most implementations, this is the extent of the changes.
However, if you used the organizationEndpoints
property to send requests to your proxy, which then relayed them to the Coveo APIs, you’ll need to make additional changes.
Atomic v3 introduces the search.proxyBaseUrl
, analytics.proxyBaseUrl
, and commerce.proxyBaseUrl
engine configuration options for such cases.
Atomic Version 2
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
// ...
organizationId: 'my-org-id',
organizationEndpoints: {
...(await getOrganizationEndpoints('my-org-id')),
search: 'https://myproxy.com/search',
}
});
searchInterface.executeFirstSearch();
})();
Atomic Version 3
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
// ...
organizationId: 'my-org-id',
search: {
proxyBaseUrl: 'https://myproxy.com/search',
},
});
searchInterface.executeFirstSearch();
})();
platformUrl
property
The already deprecated platformUrl
property was removed from the initialize
method options of every search interface component.
It was used prior to the introduction of organizationEndpoints
and has been deprecated since.
Localization
i18next compatibilityJSON
In Atomic v2, the compatibilityJSON
property in the atomic-search-interface
, atomic-insight-interface
, and atomic-recs-interface
components was set to v3
by default.
In Atomic v3, the compatibilityJSON
is automatically set to v4
.
The main change is the way that plural forms are handled.
Atomic Version 2
"past-year": {
"en": "Past year",
"fr": "Année passée"
},
"past-year_plural": {
"en": "Past {{count}} years",
"fr": "{{count}} années passées"
},
// ...
Atomic Version 3
"past-year_one": {
"en": "Past year",
"fr": "Année passée"
},
"past-year_other": {
"en": "Past {{count}} years",
"fr": "{{count}} années passées"
},
// ...
See JSON Format.
remove-filter-on
renamed to remove-inclusion-filter-on
The remove-filter-on
locale key was renamed to remove-inclusion-filter-on
in Atomic v3.
If you have custom locales using remove-filter-on
, you should update the key to remove-inclusion-filter-on
.
Atomic Version 2
"remove-filter-on": {
"en": "Remove inclusion filter for {{value}}",
// ...
},
// ...
Atomic Version 3
"remove-inclusion-filter-on": {
"en": "Remove inclusion filter for {{value}}",
// ...
},
// ...
Exports
Atomic exports multiple entry points, each meant to support different use cases and environments. To improve the inter-operability of Atomic with different industry standard tools, and to guide those tools to properly use the appropriate entry points depending on the use case, Atomic will start enforcing and specifying export fields in package.json. This means that implementations relying on non-public modules of the package will stop functioning.
Atomic Version 3
// This will be blocked entirely
import {nonPubliclyDocumentedFunction} from '@coveo/atomic/dist/nonPublicFile.js';
// Will throw an error, or won't compile
nonPubliclyDocumentedFunction();
Atomic React
The @coveo/atomic-react
package will no longer export functionality from the Headless package. It will only contain Atomic React components. Instead, you should import them directly from the @coveo/headless
package.
Atomic Version 2
import {
AtomicFacet,
AtomicText,
// This function is coming from @coveo/headless
buildSearchEngine,
// This interface is coming from @coveo/headless
Result,
} from '@coveo/atomic-react';
Atomic Version 3
import {AtomicFacet, AtomicText} from '@coveo/atomic-react';
import {buildSearchEngine, Result} from '@coveo/headless';
Also, you need to set moduleResolution": "bundler"
in your tsconfig.json
file to access secondary entry points such as @coveo/atomic-react/commerce
or @coveo/atomic-react/recommendation
.
See TypeScript module resolution for more information.
Modified behaviors
textarea
search box is now the default
To better support Relevance Generative Answering (RGA) use cases, some work was done to expand the search box input when the queries are verbose.
This required modifying the HTML for the search box input to be a <textarea>
element, as opposed to an <input type="text">
element.
In Atomic v2, an option was added on the atomic-search-box component to allow implementers to choose between a textarea
and an input
.
In Atomic v3, that option has been removed, and only one type of input, textarea
, is supported.
Atomic Version 2
<!-- Control the input type with the textarea option -->
<atomic-search-box textarea="true"></atomic-search-box>
Atomic Version 3
<!-- Option is no longer necessary, and the component will output a textarea element -->
<atomic-search-box></atomic-search-box>
queryCorrectionMode
The atomic-did-you-mean queryCorrectionMode
property default value is now next
rather than legacy
.
This means that the default behavior of the atomic-did-you-mean
component will be to use a query suggestions model for query correction rather than the index mechanism.
Removals
atomic-recs-list
and atomic-result-list
gridCellLinkTarget
property
The gridCellLinkTarget
property was removed from the atomic-recs-list
and atomic-result-list
components.
Instead of using this property, provide an atomic-result-link
in the link
slot of the atomic-result-template
component.
Atomic Version 2
<atomic-result-list grid-cell-link-target="_blank">
<atomic-result-template>
<template>
My template
</template>
</atomic-result-template>
</atomic-result-list>
Atomic Version 3
<atomic-result-list>
<atomic-result-template>
<template slot="link">
<atomic-result-link>
<!-- Moreover, you can add other attributes on the anchor element as well -->
<a slot="attributes" target="_blank"></a>
</atomic-result-link>
</template>
<template>
My template
</template>
</atomic-result-template>
</atomic-result-list>
atomic-hosted-page
and atomic-simple-builder
Use atomic-hosted-ui
instead.
atomic-load-more-children-results
The component has been removed and its functionality has been integrated into atomic-result-children
.
Atomic Version 2
<atomic-result-section-children>
<atomic-load-more-children-results></atomic-load-more-children-results>
<atomic-result-children image-size="icon">
<!-- ... -->
</atomic-result-children>
</atomic-result-section-children>
Atomic Version 3
<atomic-result-section-children>
<atomic-result-children image-size="icon">
<!-- ... -->
</atomic-result-children>
</atomic-result-section-children>
atomic-generated-answer
withRephraseButtons
and answerStyle
properties
The withRephraseButtons
and answerStyle
properties were removed from the atomic-generated-answer
component due to low usage not justifying their maintenance.
Atomic React
The following are no longer supported in Atomic React.
IIFE
Atomic React is no longer exported via CDN. While this method was useful for quick prototyping, it wasn’t recommended for production. Instead, you should install Atomic React NPM.
Analytics configuration
Atomic React no longer exposes the analytics
prop on the AtomicSearchInterface
component, as it didn’t function correctly.
Instead, you should use the engine.analytics.enabled
configuration option.
Atomic Version 2 (Not working correctly)
<AtomicSearchInterface analytics={false} />
Atomic Version 3
const engine = buildSearchEngine({
configuration: {
// ...
analytics: {enabled: false},
},
});
CommerceSearchBoxSuggestionsEvent
When implementing custom query suggestions, you need to dispatch an event of type SearchBoxSuggestionsEvent
from the registered query suggestions to the parent search box.
In v2, an event of type CommerceSearchBoxSuggestionsEvent
was instead required in Commerce implementations.
In v3, the CommerceSearchBoxSuggestionsEvent
type no longer exists.
You should use SearchBoxSuggestionsEvent
type instead.
Atomic React wrapper props
Two undocumented props were removed from the Atomic React wrapper component:
-
WrapperProps.pipeline
-
WrapperProps.searchHub
They were both marked as deprecated in v2, due to being ineffective.
Rather, if you need to set those properties client-side, use the engine
search
configuration.
const MyPage = () => {
const engine = buildSearchEngine({
configuration: {
search: {
pipeline: 'my-pipeline',
searchHub: 'my-search-hub',
},
},
}
});
return (
<AtomicSearchInterface engine={engine}>
// ...
</AtomicSearchInterface>
);
};
Or better yet, enforce those properties through authentication (see Search token authentication and API key authentication).
Headless no longer exported through Atomic
In Atomic v2, the Headless library was exported through the Atomic library. This is no longer the case in Atomic v3. Instead, you should import Headless directly in your project.
Atomic Version 2
<head>
<script type="module" src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js"></script>
<link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css" />
<script type="module">
import {
buildRedirectionTrigger,
loadAdvancedSearchQueryActions
} from 'https://static.cloud.coveo.com/atomic/v2/headless/headless.esm.js';
// ...
</script>
</head>
Atomic Version 3
<head>
<script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js"></script>
<link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css" />
<script type="module">
import {
buildRedirectionTrigger,
loadAdvancedSearchQueryActions
} from 'https://static.cloud.coveo.com/headless/v3/headless.esm.js';
// ...
</script>
</head>