# Install the Agentforce Commerce Client on SFRA

On a Storefront Reference Architecture (SFRA) storefront, install the `plugin_commerce_client` cartridge. The cartridge source is in the `plugin_commerce_client` repository in the `SalesforceCommerceCloud` GitHub organization.

This plugin renders the client chat window on every storefront page, and reads its configuration from a single Business Manager site preference. From this site preference, you can enable, disable, and customize the client.

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.

Before you begin, complete these prerequisite setup.

1. Set up the B2C Shopper Agent. See the [Shopper Agent Setup Overview](https://help.salesforce.com/s/articleView?id=cc.b2c_shopper_agent_setup_intro.htm\&type=5).
   1. Make sure you have the [Required Licenses for the B2C Shopper Agent](https://help.salesforce.com/s/articleView?id=cc.b2c_shopping_agent_licences.htm\&language=en_US\&type=5): Make sure your org has the required licenses provisioned for the B2C Shopper Agent.
   2. [Enable Agentic Commerce Search for the Shopper Agent](https://help.salesforce.com/s/articleView?id=cc.b2c_agentic_comm_search_enable.htm\&language=en_US\&type=5) so that the Shopper Agent can return relevant product results.
   3. [Create a B2C Shopper Agent Using the Automated Setup](https://help.salesforce.com/s/articleView?id=cc.b2c_shopper_agent_run_auto_setup.htm\&type=5)
2. Meet these requirements:
   - Business Manager access with permissions to edit cartridge paths.
   - Node.js 18 or later is available on a local system.
   - A WebDAV access key, which you can find in Business Manager, at **Administration | Organization | WebDAV Client Permissions**.

## Get Access to the SFRA Cartridge Repository

Access to the `plugin_commerce_client` repository in the `SalesforceCommerceCloud` GitHub organization. Anyone with Commerce Cloud Account Manager credentials can join the organization and reach the repository on GitHub.

1. Create an account at <http://github.com/join> if you don't already have an account with [github.com](https://github.com/).
2. Enable two-factor authentication for your GitHub account: <https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/>.
3. Navigate to [https://github.com/orgs/SalesforceCommerceCloud/sso](https://github.com/orgs/SalesforceCommerceCloud/sso/sign_up).
4. Log in via your Commerce Cloud Account Manager credentials.
5. Access the [Commerce Cloud GitHub repositories](https://github.com/SalesforceCommerceCloud) (login required).

Each user requires valid Account Manager credentials to authenticate. If you don't have an account, contact your B2C Commerce admin.

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.

### Related Resources

[Trailhead: Access the GitHub Repositories](https://trailhead.salesforce.com/content/learn/modules/b2c-developer-resources-and-tools/b2c-developer-access-repositories)

## Install the SFRA Cartridge for the Agentforce Commerce Client

After you gain access to the `plugin_commerce_client` repository, install the cartridge.

1. Open a terminal window.

2. Clone and build the cartridge.

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

3. Create a `dw.json` file in the main top-level folder of your SFRA project.

   - `hostname`, don't include `https://` at the beginning or a `/` at the end of the URL.
   - `password`, use the encrypted WebDAV access property as the `password`, not your Business Manager login.
   - `code-version` must match the active code version of the storefront instance. To find the version, log into the **Business Manager** for the specific instance, and go to **Administration > Site Development > Code Deployment**. Look for the active version.

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

4. Upload the cartridge.

   ```bash
   npm run uploadCartridge
   ```

5. In Business Manager, go to **Administration | Sites | Manage Sites** | your_site. Select **Settings,** and in the **Cartridges** field, prepend `plugin_commerce_client` to the string, for example, `plugin_commerce_client:app_storefront_base.`

   Always add `plugin_commerce_client` before the base cartridge in the list.

6. Generate the site metadata archive. The cartridge includes a site-import archive that creates the Commerce Client preference group and its custom preferences.

   ```bash
   npm run siteimport:zip
   ```

7. Import the site metadata archive to load the client site preferences, which allows the cartridge to read its own configuration.
   1. Go to **Administration > Site Development > Site Import & Export**.
   2. Upload the `site_import_commerce_client.zip`.
   3. Select the uploaded file, and then select **Import**.

## Configure the Client Site Custom Preferences for SFRA Storefronts

The `plugin_commerce_client` cartridge reads its configuration from one JSON site preference object in Business Manager called, Commerce Client Configuration (JSON), `cc_config`. Configure the object for the Agentforce Commerce Client to work.

The site preferences for the Agentforce Commerce Client are in one JSON object. Configure the object properties.

Rules for valid JSON:

- Format booleans outside of quotations. Example: `true`, not `"true"`. The exception is `isCartMgmtSupported`, which is intentionally the string `"true"`.
- Set `cc_widgetPosition` to `bottom-left` or `bottom-right.`
- Don't hard code `SiteId`, `Locale`, `Currency`, or auth tokens. The cartridge supplies those at runtime.

1. In Business Manager, go to **Merchant Tools | Site Preferences | Site Custom Preferences | Commerce Client**, and find the Commerce Client Configuration (JSON) setting. This example shows the minimum production configuration for the B2C Shopper Agent and the client to work together.

   ```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"
     }
   }
   ```

2. For `cc_scrt2Url`, `cc_orgId`, and `cc_esDeveloperName`, enter the values from the code snippet that you recorded previously. `cc_scrt2Url` is the SCRT2 messaging endpoint, `cc_orgId` is the 15 to 18-character Salesforce org ID, starting with `00D`, that hosts your B2C Shopper Agent. The `cc_esDeveloperName` is the Embedded Service messaging channel developer name.

3. Add the `cc_loadingMode` property to the JSON, and enter the location of the widget bundle. The options are `cdn` (default) or `static`.
   - `cdn` (default) indicates that the bundle loads from the Cimulate CDN. If your storefront uses a Content Security Policy (CSP), add Cimulate's origin domain `https://*.cimulate.ai` to these three CSP directives so the widget loads pages from these sources.

     | **Directive** | **Purpose**                  |
     | ------------- | ---------------------------- |
     | `script-src`  | Controls scripts             |
     | `style-src`   | Controls stylesheets         |
     | `connect-src` | Controls network connections |

   - `static` indicates that the widget bundle ships inside the SFRA cartridge. Use this mode when the storefront can't reach an external CDN, for example behind a strict content security policy or firewall. Build the static assets and upload the cartridge. For static mode, run these commands to use the latest widget version specified in the `@cimulate/copilot-widget` package JSON.

     ```bash
     npm run copy:static
     npm run uploadCartridge
     ```

4. (CDN Mode only) Set `cc_cdnVersion` to the release you want to run, for example, 1.46.0. To upgrade to a newer widget release, change the `cdnVersion` value. You don't have to redeploy the cartridge.

5. Optionally, add other properties to customize the appearance and behavior of the client. To see other properties, see [Customize the Agentforce Commerce Client](/docs/commerce/b2c-commerce/guide/customize-commerce-client.md). If you leave a property unset, the widget uses the cartridge default.