Install the Agentforce Commerce Client on PWA Kit

On a PWA Kit (Composable Storefront) project, you don’t embed the client with a hand-written <script> tag. You enable and configure it through a single Managed Runtime environment variable, COMMERCE_AGENT_SETTINGS. The retail-react-app template reads that variable, selects the Commerce Client provider, and injects the widget for you.

This topic covers enabling the client, the configuration shape, and the developer code path for component overrides. For the override contract itself (slots, payloads, and the API), see Component Override SDK.

Enable the client

Set the COMMERCE_AGENT_SETTINGS environment variable on your Managed Runtime environment.

Open Runtime Admin (https://runtime.commercecloud.com/).
Select your project, then the environment.
Under Environment Variables, add COMMERCE_AGENT_SETTINGS with a JSON value.

COMMERCE_AGENT_SETTINGS replaces the entire agent configuration object, so include every setting the storefront needs, not just the keys you’re changing.

A minimal working configuration selects the Commerce Client provider and sets the three connection fields:

1{
2  "enabled": "true",
3  "provider": "commerce-client",
4  "salesforceOrgId": "00DXXXXXXXXXXXXXXX",
5  "scrt2Url": "https://your-org.my.salesforce-scrt.com",
6  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
7  "cc_cdnVersion": "1.30.0"
8}

provider must be commerce-client to load this widget.
salesforceOrgId, scrt2Url, and cc_esDeveloperName are the same connection values you get from the Agentforce messaging channel’s connection snippet.
cc_cdnVersion pins the widget release loaded from the CDN. This guide documents version 1.30.0.

The same object accepts the appearance and behavior keys (cc_headerText, cc_disclaimerMarkdown, cc_theme, cc_searchConfig, cc_widgetPosition, cc_enableEscalationToAgent, cc_enableDownloadTranscript, and so on). These map to the configuration surface in Configure the Agentforce Commerce Client and Style and Theme the Widget.

Streaming of agent responses requires a capabilities version of 65 or higher. On PWA Kit this defaults to 65, so you don’t need to set cc_capabilitiesVersion explicitly.

Note

Deploy

From the template project (packages/template-retail-react-app), push a bundle to Managed Runtime:

1npm run push -- --projectSlug <project-slug>

To push and deploy to a specific target environment, add --target and --wait:

1npm run push -- --projectSlug <project-slug> --target production --wait

Roll back with config alone

Because the widget is driven entirely by COMMERCE_AGENT_SETTINGS, disable or revert it without a redeploy:

Action	Change
Disable the widget	Set `"enabled": "false"`.
Revert to a prior widget release	Set `cc_cdnVersion` to the previous version.

Component overrides on PWA Kit

Use component overrides to replace the widget’s built-in product and agent-action rendering with your own custom elements. On PWA Kit, you supply them one of two mutually exclusive ways, both through COMMERCE_AGENT_SETTINGS:

Route	Key	What It Holds
Inline map	`cc_overrides`	An object mapping override keys to custom-element tag names.
Hosted script	`cc_overridesUrl`	An HTTPS URL to a script that defines the elements and assigns `window.CimulateOverrides`.

Overrides require provider: "commerce-client" and cc_cdnVersion of 1.30.0 (any release that supports the slots you use).

The widget’s own precedence resolves overridesUrl before an inline map. The PWA Kit template inverts this: if you set both cc_overrides and cc_overridesUrl, it forwards cc_overrides and drops the URL with a console warning. Set only one.

Note

Inline map route

Register the custom element in the browser entry point, then reference its tag name from cc_overrides. Registration has to happen in the browser, because customElements doesn’t exist during server-side rendering.

Author the custom element:

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

Call the registration from the browser entry point:

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

Then map the override key to the tag name in COMMERCE_AGENT_SETTINGS:

1{
2  "enabled": "true",
3  "provider": "commerce-client",
4  "cc_cdnVersion": "1.30.0",
5  "cc_overrides": {
6    "ProductTile": "cx-product-tile"
7  }
8}

Hosted script route

Host a script on HTTPS that defines your elements and assigns window.CimulateOverrides, then point cc_overridesUrl at it:

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

Content Security Policy

The template’s app/ssr.js builds the script-src allowlist. It already includes the Cimulate origin, and it adds the origin of a valid cc_overridesUrl automatically through the getCommerceClientOverridesCspSources helper, so a hosted override script from an allowed origin loads without a manual CSP edit. Confirm these directives permit the widget:

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