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.
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 |
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_overridesUrlproperty in thecc_configsite preference to the relative path.
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.
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.
- Create the custom element as a class that extends
OverrideElementfrom@cimulate/copilot-widget/messaging, escaping every agent-supplied value.
- Register the element from the browser entry point (
app/main.jsx), becausecustomElementsisn’t available during server-side rendering.
- Map the override property to the element’s tag name in
cc_overrides:
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:
Set cc_cdnVersion to a Commerce Client version that supports the components that you override.
TBD –>
After your application registers the custom elements, pass the override map to injectMessagingWidget.