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

1git clone https://github.com/SalesforceCommerceCloud/plugin_commerce_client.git
2cd plugin_commerce_client
3npm install

Create a dw.json file in the project root:

1{
2  "hostname": "your-instance.dx.commercecloud.salesforce.com",
3  "username": "your-email@example.com",
4  "password": "your-webdav-access-key",
5  "code-version": "version1"
6}

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:

1npm 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:

1plugin_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:

1npm run siteimport:zip

Then import it in Business Manager:

Go to Administration > Site Development > Site Import & Export.
Upload the generated site_import_commerce_client.zip.
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:

1{
2  "cc_scrt2Url": "https://your-org.my.salesforce-scrt.com",
3  "cc_orgId": "00DXXXXXXXXXXXXXXX",
4  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
5  "cc_enabled": true,
6  "cc_routingAttributes": {
7    "isCartMgmtSupported": "true"
8  }
9}

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 and Style and Theme the Widget. 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.

1{
2  "cc_loadingMode": "cdn",
3  "cc_cdnVersion": "1.30.0"
4}

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

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:

1npm run copy:static
2npm run uploadCartridge

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

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.

Note

Verify the deployment

Open any storefront page and open your browser’s developer tools.
In the Network tab, confirm the widget bundle (messaging.umd.js) returns a 200.
With cc_isDevelopment set to true, check the Console for [CommerceClient] messages.
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`