---
schema_version: "1"
id: 7d718a072d220b24198d24f187aa83ee160064fa6030a300726103746ba37f17
title: Install the Agentforce Commerce Client on SFRA
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-sfra.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 1b80627bea8a2aa6653726d7899a307bea624e877af7b2580a24486db6c6a053
products:
  - Composable Storefront
  - Salesforce APIs
---
# Install the Agentforce Commerce Client on SFRA

On a Storefront Reference Architecture (SFRA) storefront, you don't embed the client with a hand-written `<script>` tag. You install the `plugin_commerce_client` cartridge, which renders the widget on every storefront page and reads its configuration from a single Business Manager Site Preference. Merchants can then enable, disable, and customize the widget without a code deploy.

`plugin_commerce_client` is the only cartridge you need. Earlier setups paired it with a separate `plugin_shopper_agent` cartridge; that cartridge is no longer required and must not appear in the site cartridge path.

The cartridge supports two ways to load the widget bundle: from the CDN (the default and most common path) or from static assets bundled into the cartridge. Both are covered below.

## Prerequisites

- Business Manager access with permissions to edit cartridge paths (**Administration > Sites**), import site metadata (**Administration > Site Development**), and edit Site Preferences (**Merchant Tools > Custom Preferences**).
- The server-side Agentforce setup complete, so you have the SCRT2 URL, Organization ID, and Embedded Service developer name from the messaging channel's connection snippet.
- Node.js 18 or later.
- A WebDAV access key (**Administration > Organization > WebDAV Client Permissions**).

## Get access to the cartridge repository

The cartridge source is in the [`plugin_commerce_client`](https://github.com/SalesforceCommerceCloud/plugin_commerce_client) repository in the `SalesforceCommerceCloud` GitHub organization. Access is self-service: any developer with Commerce Cloud Account Manager credentials can join the organization and reach the repository without a manual access request.

Before you request access, set up your GitHub account:

- Enable non-SMS two-factor authentication (2FA) on your GitHub account, using an authenticator app (TOTP), a passkey, or a hardware security key. SMS-based 2FA isn't accepted by the organization's policy and causes silent access failures.
- Have your Commerce Cloud Account Manager credentials ready. These are the same credentials you use for other SFRA plugin repositories.

Then follow the [B2C Commerce repository access guide](https://trailhead.salesforce.com/content/learn/modules/b2c-developer-resources-and-tools/b2c-developer-access-repositories) on Trailhead. After you join the `SalesforceCommerceCloud` organization, you're automatically added to the Community team, which includes `plugin_commerce_client`. If access doesn't work, confirm that you removed SMS as a 2FA method on your GitHub account.

## Install the cartridge

Clone and build the cartridge:

```sh
git clone https://github.com/SalesforceCommerceCloud/plugin_commerce_client.git
cd plugin_commerce_client
npm install
```

Create a `dw.json` file in the project root:

```json
{
  "hostname": "your-instance.dx.commercecloud.salesforce.com",
  "username": "your-email@example.com",
  "password": "your-webdav-access-key",
  "code-version": "version1"
}
```

Use your WebDAV access key as the password, not your Business Manager login. The `hostname` takes no protocol prefix or trailing slash, and `code-version` must match the active code version on the instance. Then upload the cartridge:

```sh
npm run uploadCartridge
```

## Add the cartridge to the site path

Go to **Administration > Sites > Manage Sites > [your site] > Settings** and add `plugin_commerce_client` to the front of the **Cartridges** field, before the base cartridge:

```
plugin_commerce_client:app_storefront_base
```

B2C Commerce resolves templates left to right, so `plugin_commerce_client` has to precede `app_storefront_base` for its page overlay to take effect. If your site path includes other cartridges, keep `plugin_commerce_client` ahead of the base cartridge in the list.

## Import the site metadata

The cartridge ships a site-import archive that creates the Commerce Client preference group and its custom preferences. Without this import, the widget's preferences don't exist and the cartridge can't read its configuration.

Generate the archive:

```sh
npm run siteimport:zip
```

Then import it in Business Manager:

1. Go to **Administration > Site Development > Site Import & Export**.
2. Upload the generated `site_import_commerce_client.zip`.
3. Select the uploaded file, and then select **Import**.

## Configure the widget

The cartridge reads its entire configuration from one JSON Site Preference, **Commerce Client Configuration (JSON)** (`cc_config`). Go to **Merchant Tools > Site Preferences > Custom Preferences > Commerce Client** and set `cc_config` to a JSON object.

A minimal production configuration sets the three connection fields, enables the widget, and passes the routing attributes the agent needs:

```json
{
  "cc_scrt2Url": "https://your-org.my.salesforce-scrt.com",
  "cc_orgId": "00DXXXXXXXXXXXXXXX",
  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
  "cc_enabled": true,
  "cc_routingAttributes": {
    "isCartMgmtSupported": "true"
  }
}
```

The three connection fields come from your Agentforce messaging channel: `cc_scrt2Url` is the SCRT2 messaging endpoint, `cc_orgId` is the 18-character ID of the Salesforce org that hosts your Agentforce agent, and `cc_esDeveloperName` is the Embedded Service messaging channel developer name. `cc_scrt2Url`, `cc_orgId`, and `cc_esDeveloperName` are required; the widget doesn't render without all three.

The same object accepts optional appearance and behavior keys, including `cc_widgetPosition` (`bottom-left` or `bottom-right`), `cc_isOpen`, `cc_showFab`, `cc_isDevelopment`, `cc_headerText`, `cc_disclaimerMarkdown`, and the nested `cc_theme` and `cc_searchConfig` objects. These map to the same configuration surface described 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). Omit a key to keep the cartridge default.

A few rules keep the JSON valid:

- Booleans must be real JSON booleans (`true`, not `"true"`), except `isCartMgmtSupported`, which is intentionally the string `"true"`.
- `cc_widgetPosition` must be `bottom-left` or `bottom-right`, and `cc_loadingMode` must be `cdn` or `static`.
- Don't hard code session values such as `SiteId`, `Locale`, `Currency`, or auth tokens. The cartridge supplies those at runtime.

## Choose a bundle loading mode

The `cc_loadingMode` key in `cc_config` selects where the widget bundle comes from.

### CDN mode (default)

In CDN mode (`"cc_loadingMode": "cdn"`), the cartridge loads the bundle from the Cimulate CDN. Set `cc_cdnVersion` to the release you want to run. This guide documents version `1.30.0`. Because the version is a config value, you can move to a newer widget release by changing it, with no cartridge redeploy.

```json
{
  "cc_loadingMode": "cdn",
  "cc_cdnVersion": "1.30.0"
}
```

CDN mode is the recommended path for most storefronts. It requires the storefront to reach the CDN, so if your storefront enforces a Content Security Policy, allowlist the Cimulate origin (see [Content Security Policy](#content-security-policy)).

### Static mode

In static mode, the widget bundle ships inside the cartridge instead of loading from the CDN. Use it when the storefront can't reach an external CDN, for example behind a strict Content Security Policy (CSP) or firewall. Build the static assets and upload the cartridge:

```sh
npm run copy:static
npm run uploadCartridge
```

Then set `"cc_loadingMode": "static"` in `cc_config`.

**note:** In static mode, you own version updates. The bundle is whatever `@cimulate/copilot-widget` version the cartridge's dependencies resolve to, so update that dependency and rerun `npm run copy:static` and `npm run uploadCartridge` to move to a newer widget release. The `cc_cdnVersion` value has no effect in static mode.

## Verify the deployment

1. Open any storefront page and open your browser's developer tools.
2. In the **Network** tab, confirm the widget bundle (`messaging.umd.js`) returns a 200.
3. With `cc_isDevelopment` set to `true`, check the **Console** for `[CommerceClient]` messages.
4. Confirm the chat launcher appears in the configured position.

## Content Security Policy

If your storefront enforces a Content Security Policy, allowlist the Cimulate origin so the bundle, styles, and connection are permitted:

| Directive | Value |
| --- | --- |
| `script-src` | `https://*.cimulate.ai` |
| `style-src` | `https://*.cimulate.ai` |
| `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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-the-commerce-client.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md)