Deploy Commerce Client Overrides

You can deploy overrides by using a hosted script or an inline map. The supported method depends on your storefront type.

Hosted script (recommended): Host an override script that defines your custom elements and assigns their mappings to window.CimulateOverrides. Then configure your storefront to load the script.
Inline map: With an inline map, you specify an object mapping that replaces properties with custom element tag names. An inline map passes your overrides directly to the widget, so you don’t need to host a separate script. Register each custom element first, then reference its tag name in the map.

Storefront	Hosted Script	Inline Map
SFRA	`cc_overridesUrl` in the `cc_config` site preference	N/A
PWA Kit	`cc_overridesUrl` in `COMMERCE_AGENT_SETTINGS`	`cc_overrides` in `COMMERCE_AGENT_SETTINGS`
Storefront Next

When more than one override source is present, the widget resolves them in this order:

Storefront	First	Second	Third
SFRA	`overridesUrl` (hosted script)		N/A
PWA Kit	`cc_overrides` (inline map)	`cc_overridesUrl` is dropped, with a console warning	N/A
Storefront Next			N/A
Custom application `injectMessagingWidget`	N/A	`Overrides` (inline map)	`window.CimulateOverrides` (Set before the Built-in UI).

If one of these methods aren’t present or fails, then the widget keeps its built-in UI.

Note

If a hosted script is from an allowed origin, don’t edit a content security policy. The PWA Kit template allows scripts from the configured location.

Confirm these directives permit the widget:

Directive	Value
`script-src`	`https://*.cimulate.ai` (plus your `cc_overridesUrl` origin)
`connect-src`	`https://*.cimulate.ai`
`style-src`	`https://*.ciumlate.ai`

Deploy Overrides to SFRA Using a Hosted Script

The plugin_commerce_client cartridge loads overrides from a static script inside the cartridge.

Add the script to the cartridge at cartridge/static/default/jscript/cimulate/overrides.js.
Define your custom elements, and assign window.CimulateOverrides.

Because window.CimulateOverrides is a plain object, multiple files can point to it. Merge rather than replace so the files coexist, and make sure each runs synchronously at the top level before the widget’s first render.

Upload the cartridge by entering npm run uploadCartridge. See Install the Agentforce Commerce Client on SFRA.
Set the cc_overridesUrl property in the cc_config site preference to the relative path.

1{
2   "cc_overridesUrl": "/jscript/cimulate/overrides.js"
3 }

A relative path avoids a cross-origin request, and the cartridge derives the script-src CSP entry from the preference automatically. For the full cartridge install, dw.json, and site-path steps, see Install the Agentforce Commerce Client on SFRA.

Deploy Overrides for PWA Kit Using an Inline Map

The retail-react-app template accepts overrides through COMMERCE_AGENT_SETTINGS as an inline cc_overrides map.

Create the custom element for each slot you want to override, and register it with a guarded define.
Call the registration from the browser entry point.
Pass the map, where each key is a component name and each value is the tag name of its custom element.

Don’t configure both cc_overrides and cc_overridesUrl. When both are present, the PWA Kit template uses cc_overrides and ignores the URL.

Note

Create the custom element as a class that extends OverrideElement from @cimulate/copilot-widget/messaging, escaping every agent-supplied value.

1// app/components/shopper-agent/overrides/product-tile-element.js
2 import { OverrideElement } from "@cimulate/copilot-widget/messaging";
3
4 class ProductTileElement extends OverrideElement {
5   render() {
6     const { payload, api } = this.props || {};
7     // Build your DOM here. Escape every agent-supplied value.
8   }
9 }
10
11 export function registerProductTile() {
12   if (!customElements.get("cx-product-tile")) {
13     customElements.define("cx-product-tile", ProductTileElement);
14   }
15 }

Register the element from the browser entry point (app/main.jsx), because customElements isn’t available during server-side rendering.

1// app/main.jsx
2 import { registerProductTile } from "./components/shopper-agent/overrides/product-tile-element";
3
4 registerProductTile();

Map the override property to the element’s tag name in cc_overrides:

1{
2   "provider": "commerce-client",
3   "cc_overrides": {
4     "ProductTile": "cx-product-tile"
5   }
6 }

Deploy Overrides for PWA Kit Using a Hosted Script

Set cc_overridesUrl to an HTTPS script that defines your elements and assigns window.CimulateOverrides. The script must define the custom elements and assign their override mappings to window.CimulateOverrides.

Example:

1{
2  "enabled": "true",
3  "provider": "commerce-client",
4  "cc_cdnVersion": "1.46.0",
5  "cc_overridesUrl": "https://cdn.example.com/commerce-client/overrides.js"
6}

Set cc_cdnVersion to a Commerce Client version that supports the components that you override.

Note

Deploy Overrides for Storefront Next

TBD –>

Use an Inline Map When You Call injectMessagingWidget

After your application registers the custom elements, pass the override map to injectMessagingWidget.

1injectMessagingWidget({
2  elementId: "messaging-widget",
3  messagingConfig: {
4    scrt2Url: "https://your-org.my.salesforce-scrt.com",
5    orgId: "00Dxx0000000000",
6    esDeveloperName: "Your_Messaging_Channel",
7  },
8  overrides: {
9    ProductTile: "product-card",
10    recentOrders: "cx-recent-orders",
11  },
12});