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.

Set the COMMERCE_AGENT_SETTINGS environment variable on your Managed Runtime environment.

1. Open Runtime Admin (https://runtime.commercecloud.com/).
2. Select your project, then the environment.
3. 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:

• 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.

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

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

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

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:

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

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:

Call the registration from the browser entry point:

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

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

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:

• Agentforce Commerce Client Overview
• Install the Agentforce Commerce Client on SFRA
• Configure the Agentforce Commerce Client
• Component Override SDK