Upgrade from v2 to v3

This is for:

Developer System Administrator

Quantic v3 introduces changes that improve the library’s performance and usability. Notably, Quantic v3 uses organization endpoints by default.

Important
The following are breaking changes from Quantic v2 to v3

Organization endpoints

Organization endpoints is a feature that improves separation of concerns and resiliency, making multi-region and data residency deployments smoother. Starting with Quantic v3, the usage of organization endpoints will be enforced, as opposed to optional in v2.

The CoveoTokenProvider class will change to always use the organization endpoints. Since you have most likely copied and changed this class to implement your own search token provider, you should update your implementation to use the organization endpoints as well.

Update custom components for analytics events

Warning

Update any custom search interface components you created by copying out-of-the-box (OOTB) Quantic v2 components. Without this update, the components won’t send analytics events correctly in v3.

Why custom components need updates

Headless v3 changed the default analytics tracking method to Event Protocol. However, Event Protocol doesn’t fully support Salesforce (except for Commerce implementations). To address this limitation, Quantic v3 sets analyticsMode: 'legacy' in out-of-the-box components such as QuanticSearchInterface, QuanticCaseAssistInterface and QuanticInsightInterface so they use the Coveo UA library.

Custom components based on v2 code don’t include this configuration. When you upgrade these components to v3, they default to Event Protocol, which prevents analytics events from working in Salesforce.

This issue affects:

  • Custom search interface components

  • Custom case assist interface components

  • Custom insight interface components

Update your custom components

Configure your custom components to use legacy analytics mode.

Add the following to your custom component’s analytics configuration. Typically, to the connectedCallback function:

analytics: {
  analyticsMode: 'legacy', 1
}
1 Sets analyticsMode to use Coveo UA library instead of Event Protocol, which doesn’t fully support Salesforce.

To match the full OOTB component configuration (including origin tracking and version metadata), see the complete examples:

Event Protocol support

Coveo for Commerce supports Event Protocol. For all other implementations, set analyticsMode to legacy.

Verify your analytics events

Confirm that your custom components send analytics events correctly:

  1. Open your browser’s DevTools.

  2. Select the Network tab.

  3. Perform a search or interaction.

  4. Check the network calls for the Coveo Analytics endpoint.

If you see calls to https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1, the component uses Event Protocol (which doesn’t work in Salesforce). After you apply the fix, you should see calls to Coveo UA analytics endpoints instead.

For more information, see Custom components in Quantic 3+ aren’t sending analytics events (requires Coveo Community login).

Renamed

The following elements were renamed without changes to their underlying functionality.

QuanticResultBadge

The component has been replaced by QuanticResultTag

Custom events

Some custom events emitted by Quantic were renamed with the quantic__ prefix to make them easier to identify.

  • rating → quantic__rating

  • headerclick → quantic__headerclick

  • headerkeydown → quantic__headerkeydown

  • renderfacet → quantic__renderfacet

  • selectvalue → quantic__selectvalue

  • citationhover → quantic__citationhover

  • like → quantic__like

  • dislike → quantic__dislike

  • pressexplainwhy → quantic__pressexplainwhy

  • registerresulttemplates → quantic__registerresulttemplates

  • select → quantic__select

  • deselect → quantic__deselect

  • loadingstatechange → quantic__loadingstatechange

  • change → quantic__change

  • registerrecommendationtemplates → quantic__registerrecommendationtemplates

  • haspreview → quantic__haspreview

  • suggestionlistrender → quantic__suggestionlistrender

  • arialivemessage → quantic__arialivemessage

  • registerregion → quantic__registerregion

  • tab_rendered → quantic__tabrendered

Removed

Rephrase buttons

These buttons were removed in v3, due to low usage not justifying their maintenance.

withRephraseButtons, answerStyle, and multilineFooter properties of the QuanticGeneratedAnswer component

These properties were used for the rephrase buttons and were removed in v3.

QuanticGeneratedAnswerRephraseButtons component

This undocumented rephrase button component was removed in v3.

quantic_OpensInSalesforceSubTab custom label

This undocumented custom label was removed. Unless you had custom logic based on this label, the change should be transparent.

resetSelection and blur methods

These methods were exposed on the internal QuanticSearchBoxInput component, which was used by the QuanticSearchBox and QuanticStandaloneSearchBox components. The methods were removed because they weren’t used.

The useCase property was removed. It didn’t do anything, so the change should be transparent.

Changed

The following changes were made.

QuanticDocumentSuggestion

quanticDocumentSuggestion.showQuickview, which was set to false by default, has been replaced by quanticDocumentSuggestion.withoutQuickview, which is also set to false by default. If you were setting showQuickview to true, you can remove this property from your code.

Quantic Version 2

<c-quantic-document-suggestion engine-id={engineId} max-documents="5" show-quickview></c-quantic-document-suggestion>

Quantic Version 3

<c-quantic-document-suggestion engine-id={engineId} max-documents="5"></c-quantic-document-suggestion>

If you were setting showQuickview to false or leaving it as false by default, you can replace it with without-quickview set to true.

Quantic Version 2

<c-quantic-document-suggestion engine-id={engineId} max-documents="5"></c-quantic-document-suggestion>

Quantic Version 3

<c-quantic-document-suggestion engine-id={engineId} max-documents="5" without-quickview></c-quantic-document-suggestion>

QuanticSmartSnippetSource title and uri properties

Both the title and uri properties have been replaced by the source property.

This change is unlikely to affect you because it’s used by the QuanticSmartSnippet and the QuanticSmartSnippetSuggestions directly. As a result, you aren’t required to use QuanticSmartSnippetSource directly.

If you were using the QuanticSmartSnippetSource directly, you’ll need to use source instead of title and uri.

Quantic Version 2

<!-- html -->
<c-quantic-smart-snippet-source engine-id={engineId} title="{sourceTitle}" uri="{sourceUri}">
</c-quantic-smart-snippet-source>
// js
get sourceTitle() {
    // ...
}
get sourceUri() {
    // ...
}

Quantic Version 3

<!-- html -->
<c-quantic-smart-snippet-source engine-id={engineId} source="{source}">
</c-quantic-smart-snippet-source>
// js
get source() {
    clickUri: //...
    title: //...
}

QuanticSearchInterface, QuanticInsightInterface and QuanticCaseAssistInterface originLevel3 default value

The originLevel3 property default value was changed from default to document.referrer.

This change should be transparent unless you were doing something specific with the originLevel3 property in your code or Coveo Analytics reports.

Relevance Generative Answering (RGA) citation clicks now tracked as regular click events

As of the Quantic v3.2.0 release, Coveo Relevance Generative Answering (RGA) citation clicks are now tracked as regular click events instead of custom click events in Coveo Analytics reports. As a result, citation click events now have a click rank value of 1. Additionally, the click Event Cause value is set to generatedAnswerCitationClick.

This change applies regardless of the tracking protocol (Coveo UA or Coveo Event Protocol) used.

Moved

The following example components were moved to the /examples folder and are no longer part of the Quantic package.

  • packages/quantic/force-app/main/default/lwc/exampleSearch to packages/quantic/force-app/examples/main/lwc/exampleSearch

  • packages/quantic/force-app/main/default/lwc/exampleStandaloneSearchbox to packages/quantic/force-app/examples/main/lwc/exampleStandaloneSearchbox

This change should be transparent, since examples aren’t meant for production use.