---
schema_version: "1"
id: a3c6200addd3754101b9b26e64f8acb58d4c41203718db335738d08ebd6fdeef
title: Install the Agentforce Commerce Client on PWA Kit
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/install-on-pwa-kit.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-pwa-kit.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 52476fc87e445cb8949dfeaed547cee290efe0f2daed331c6eb508721c6b7ca1
products:
  - Composable Storefront
  - Salesforce APIs
---
# 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md).

## Enable the client

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:

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "salesforceOrgId": "00DXXXXXXXXXXXXXXX",
  "scrt2Url": "https://your-org.my.salesforce-scrt.com",
  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
  "cc_cdnVersion": "1.30.0"
}
```

- `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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md) and [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md).

**note:** 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.

## Deploy

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

```sh
npm run push -- --projectSlug <project-slug>
```

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

```sh
npm 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).

**note:** 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.

### 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:

```js
// app/components/shopper-agent/overrides/product-tile-element.js
import { OverrideElement } from "@cimulate/copilot-widget/messaging";

class ProductTileElement extends OverrideElement {
  render() {
    const { payload, api } = this.props || {};
    // Build your DOM here. Escape every agent-supplied value.
  }
}

export function registerProductTile() {
  if (!customElements.get("cx-product-tile")) {
    customElements.define("cx-product-tile", ProductTileElement);
  }
}
```

Call the registration from the browser entry point:

```js
// app/main.jsx
import { registerProductTile } from "./components/shopper-agent/overrides/product-tile-element";

registerProductTile();
```

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

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "cc_cdnVersion": "1.30.0",
  "cc_overrides": {
    "ProductTile": "cx-product-tile"
  }
}
```

### Hosted script route

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

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "cc_cdnVersion": "1.30.0",
  "cc_overridesUrl": "https://cdn.example.com/commerce-client/overrides.js"
}
```

### 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` |

## Related resources

- [Agentforce Commerce Client Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/agentforce-commerce-client-overview.md)
- [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)