Install the Agentforce Commerce Client one of two ways: as a <script> tag that loads a UMD bundle from the CDN, or as the @cimulate/copilot-widget npm package in a React application.
On an SFRA storefront, don’t embed the client with a <script> tag. Install the plugin_commerce_client cartridge and configure the widget from Business Manager instead. See Install the Agentforce Commerce Client on SFRA.
On a PWA Kit storefront, don’t embed the client with a <script> tag either. You enable it through the COMMERCE_AGENT_SETTINGS Managed Runtime environment variable. See Install the Agentforce Commerce Client on PWA Kit.
Note
The CDN approach is a drop-in integration for any storefront. Load the bundle, add a container element, and call the injection function.
The bundle URL follows this pattern:
1https://cdn.search.cimulate.ai/copilot-widget/<version>/messaging.umd.jsPin <version> to a specific release (for example, 1.30.0) so a future release can’t change your storefront’s behavior without an explicit upgrade. The bundle also ships a matching CSS file at the same path with a .css extension. The messaging.umd.js bundle exposes the global window.CimulateMessaging.
1<div id="messaging-widget"></div>
2<script src="https://cdn.search.cimulate.ai/copilot-widget/1.30.0/messaging.umd.js"></script>
3<script>
4 CimulateMessaging.injectMessagingWidget({
5 elementId: "messaging-widget",
6 messagingConfig: {
7 scrt2Url: "https://your-org.my.salesforce-scrt.com",
8 orgId: "00Dxx0000000000",
9 esDeveloperName: "Your_Messaging_Channel",
10 },
11 });
12</script>injectMessagingWidget requires messagingConfig with scrt2Url, orgId, and esDeveloperName. If messagingConfig is missing, or any of those three fields is missing, the widget logs an error and does not render.
Container timing
Both injection functions take an elementId that names the container element to render into. If the element already exists when you call the function, the widget renders immediately. If it doesn’t exist yet, the widget starts a MutationObserver and renders as soon as the element appears, or logs an error after a timeout (5000 ms by default; override with the timeout option). This design supports injecting the widget on storefronts where the container is added asynchronously, such as single-page apps and dynamic page builders.
For a React application, install the package and import the component and injection helpers for your mode.
1npm install @cimulate/copilot-widgetThe package requires React 18 (react and react-dom at ~18.3.1) as peer dependencies.
import { AgentForceWidget } from “@cimulate/copilot-widget/messaging”;
<AgentForceWidget messagingConfig={{ scrt2Url: “https://your-org.my.salesforce-scrt.com”, orgId: “00Dxx0000000000”, esDeveloperName: “Your_Messaging_Channel”, }} />;
1**Import the styles**
2
3Import the widget stylesheet:
4
5```ts
6import "@cimulate/copilot-widget/css/messaging";@cimulate/copilot-widget follows semantic versioning. Each released version is published on merge and recorded in the package’s changelog, newest first. Before you upgrade a pinned version, review the changelog for the releases between your current version and the target so you can account for fixes and additive changes. Both the CDN URL and the npm version range are places to pin a known-good version.
The changelog is public, so you can check what’s supported in a release before you upgrade:
@cimulate/copilot-widget package page on npm.changelog.md in the file list to see what changed, was added, or was fixed in each version.
j