副驾驶部件 SDK
Cimulate 的 Copilot Widget SDK 是一个 React 组件库, 允许您将我们的 Copilot 部件嵌入您的应用程序 .
安装
要求节点++22.1.5.0和npm++10.9.2
npm install @cimulate/copilot-widget
国家预防机制的东道方必须提供 react 财务报告和审定财务报表 react-dom (单位:千美元)^18.3 || ^19) (中文(简体) ). 公布的无害环境管理文物从东道主进口这些同龄人(没有捆绑)。 CDN/小额供资 <script> 安装没有改变, 仍然捆绑 React .
套装大小快照
使用 npm run measure:bundle-sizes 用于在 gzip 大小之前/之后捕获以优化。 刷新后从此目录中运行全部 npm run build 这样 dist/ 匹配正在测试的代码.
1会话 = 1乘以下 .tmp/bundle-sizes/<DD-MM-YYYY-HHmmss>/ 与 bundle-sizes.before.json 财务报告和审定财务报表 bundle-sizes.after.json。 。 。 . .tmp/ 粘贴 --diff 如果您需要持久记录,则将表格输入公关.
# 1. Baseline (before the change)
npm run build
npm run measure:bundle-sizes -- --before
# 2. Apply the change, rebuild, capture after
npm run build
npm run measure:bundle-sizes -- --after
# 3. Diff the latest session
npm run measure:bundle-sizes -- --diff
- 在每次抓获之前建构; stale
dist/生成错误的数字. - 每届更改一次——运行新的
--before每个优化/PR. - 不要再开始另一个
--before直到你写完--after编号 :--diff用于当前对;--after赤裸裸的--diff总是使用 最新消息 时间戳目录. - 明确区分出一对老夫妇:
npm run measure:bundle-sizes -- --diff \
.tmp/bundle-sizes/<timestamp>/bundle-sizes.before.json \
.tmp/bundle-sizes/<timestamp>/bundle-sizes.after.json
游戏场
反演 App 游戏场
npm start
模拟反应环境。 由于Vite通过热模块替换服务源——不需要全面构建,更改在浏览器中即时反映,因此在本地开发上更快. 这是客户最合适的测试游乐场,他们将把部件集成到基于反应的商店前端.
设置在 src/App.tsx。可以修改的示例配置 :
// Theme definitions
const THEMES: Record<string, ThemeConfig> = {
sfra: {
primaryColor: "#0070D2",
fontFamily: '"Helvetica Neue", Arial, sans-serif',
backgroundColor: "#F7F7F7",
// ...
},
"storefront-next": {
primaryColor: "#000000",
fontFamily: '"Inter", sans-serif',
backgroundColor: "#FFFFFF",
// ...
},
};
// Copilot mode props
<CopilotWidget
apiKey={apiKey}
theme={currentTheme}
logoUrl="https://example.com/logo.png"
headerText="Cimulate Copilot"
isDevelopment={true}
/>
// Agentforce/Messaging mode props
<AgentForceWidget
headerText="Commerce Client"
disclaimerMarkdown="This is AI, *be careful*."
isDevelopment={true}
theme={currentTheme}
searchConfig={{
placeholder: "Find me cutting-edge outdoor gear",
buttonType: "icon",
buttonIcon: "arrow",
}}
messagingConfig={{
scrt2Url: "",
orgId: "",
esDeveloperName: "AgentForce",
}}
/>
通讯模式 : 附录
?ccDevMode=true到页面 URL 强制isDevelopment在运行时(设置终点+动词记录),不需要重新部署.
HTML / CDN 集成游戏场
npm run preview
最常见的整合方法,因为它是框架不可知性的. 部件的任何更改都应该在这个操场上测试. 当地发展速度较慢,因为它必须生产出一个完整的三件文物(主捆绑,副驾驶分捆绑,发短信分捆绑),并且需要在每个变化上重建.
设置在 public/index.html。可以修改的示例配置 :
<script>
// Widget injection with configuration
injectCopilotWidget({
elementId: "root",
apiKey: "INSERT_YOUR_API_KEY_HERE",
componentConfig: { isOpen: true, options: { dialogPosition: "bottom-right" } },
isDevelopment: true,
mode: "copilot",
theme: {
primaryColor: "#000000",
fontFamily: '"Inter", sans-serif',
backgroundColor: "#FFFFFF",
},
headerText: "Commerce Client",
searchConfig: {
placeholder: "Find me cutting-edge outdoor gear",
buttonType: "icon",
buttonIcon: "arrow",
},
});
// Event handlers for programmatic control
const { eventHandlers } = window["cimulate-copilot-widget"];
eventHandlers.search.updateSearchQuery("running shoes");
eventHandlers.components.setWidgetType("modal"); // "chat" | "dialog" | "modal"
eventHandlers.components.toggleWidgetOpen(true);
eventHandlers.pdp.setPdpContext({ productId: "product-123" });
eventHandlers.browse.setBrowseContext({ categoryId: "outdoor-gear" });
// Messaging mode: submit a query from a storefront search bar or embedded question
const { sendMessage, eventHandlers: messagingHandlers } = window.CimulateMessaging;
sendMessage("running shoes");
messagingHandlers.components.toggleWidgetOpen(true);
</script>
通讯页面上下文
消息集成通过通用的页面折叠式API提供规范的产品详细页 (PDP) 或搜索结果页 (SRP) 存储前端状态:
import { eventHandlers } from "@cimulate/copilot-widget/messaging";
eventHandlers.pageContext.set({
type: "pdp",
id: "product-123",
display: {
name: "Deep Cleansing Foam",
imageUrl: "https://store.example.com/products/foam.jpg",
},
});
eventHandlers.pageContext.set({
type: "srp",
query: "running shoes",
refinements: [{ name: "color", values: ["blue"] }],
minPrice: 50,
maxPrice: 150,
});
const current = eventHandlers.pageContext.get();
eventHandlers.pageContext.clear();
refinements, (中文(简体) ), minPrice,以及 maxPrice 对 SRP 上下文是可选的。 部件省略了空的改进和未定义的价格界限 。 PDP和SRP的背景是相互排斥的.
种子页面上下文一次(形状与 eventHandlers.pageContext.set,通过 messagingConfig.initialPageContext 与 enablePageContext: true。之后的运行时间更新仍然通过事件处理器进行.
<AgentForceWidget
mode="messaging"
messagingConfig={{
enablePageContext: true,
initialPageContext: {
type: "srp",
query: "running shoes",
refinements: [{ name: "color", values: ["blue"] }],
minPrice: 50,
maxPrice: 150,
},
// existing SCRT2 fields...
}}
/>
与 messagingConfig.enablePageContext,部件当shop发送短信并重用它进行重试和会话恢复时,将页面上下文抓取。 每个 PDP 或 SRP 上下文切换后的第一个文本消息都会在用户泡上方获得一个分割符. 更改页面从不单独发送消息 。 文件上传不包含页面上下文或创建分隔符.
可选的 PDP display 字段设置产品芯片和分割符的名称和图像。 SRP上下文显示可移动芯片并带有搜索图标和 Search: "query";其分隔符使用相同的标签. 一次只显示一个上下文芯片. 删除芯片可以清除页面上下文, 因此下一个信件没有上下文或分隔符 。 芯片仍然可见,用于同一产品或搜索查询上的后期消息. 设置 SRP 上下文替换了 PDP 芯片,而设置 PDP 上下文替换了 SRP 芯片.
通讯卡
消息集成 推动当前篮子 eventHandlers.cart.update。仅从邮件条目中调用它 : window.CimulateMessaging.eventHandlers.cart.update(cart) 或以下输入的国家预防机制。 副驾驶的条目没有曝光.
import { eventHandlers } from "@cimulate/copilot-widget/messaging";
eventHandlers.cart.update({
id: "cart-1",
currencyCode: "USD",
subtotal: 90,
total: 90,
items: [
{
itemId: "line-1",
productId: "SKU-1",
name: "Men's Rovereto Running Shoes",
imageUrl: "https://store.example.com/products/shoes.jpg",
quantity: 1,
itemSubtotal: 90,
originalSubtotal: 90,
variants: [{ lbl: "Color", type: "color", value: "Black / White" }],
},
],
});
对象为全篮子(CartDetails),不是数量分贝. 一个空的 items 数组表示空推车。 无有效载荷 items 数组被忽略 。 部件挂起前的呼叫被忽略 .
在部件被挂起后, 在页面加载时, 在部件外的shop 更改篮子后, 在恢复对话后再次调用它 。 聊天中最新的推车消息 更新到那个篮子。 旧的手推车信息保持不变 电话没发出 cimulate:cart-update下一个代理推车的结果与那个篮子比较.
勾起和承诺前钩
Lint 和 npm 脚本本地格式化 :
npm run lint # prettier --check + eslint
npm run lint:fix # prettier --write + eslint --fix
ESLint 执行来自 AGENTS.md 通过两项当地规则(local/banner-comments, (中文(简体) ), local/redundant-identifier-comment 内 eslint-rules/) (中文(简体) ).
承诺前的钩子( A).pre-commit-config.yaml)在副驾驶-widget文件上运行更漂亮的+eslint,在格式化/lint出错时失败了承诺. 用同样的 pre-commit 框架作为 Python 次级项目(见 文件/开发/开发-工作流程) (中文(简体) ).
npm run start 财务报告和审定财务报表 npm run preview 自动为您安装此钩子( 通过 scripts/ensure-precommit.sh),只要 pre-commit 工具在您的路径上。 如果你看到一个 pre-commit' is NOT installed 在启动 dev 服务器时警告, 安装此工具, 它会在下一个启动时自动连接 :
brew install pre-commit # macOS (recommended — avoids pyenv/venv shim issues)
pip install pre-commit # any platform
要手动设置钩子( 或者如果你不使用 Dev 服务器), 请从此目录中运行一次 :
cd javascript/copilot-widget
brew install pre-commit # or: pip install pre-commit
pre-commit install
钩子只是编了文件, 所以在别处存在的问题不会阻碍你的承诺.
发布流程
该项目遵循基于干线的开发——所有更改直接合并到 master。该软件包使用语义化版本;将版本打入 package.json 在合并之前。 注意倒向相容性,因为客户现有的执行依赖于公共API.
出版由 构建并发布 Javascript 软件包 GitHub 动作工作流程 (.github/workflows/build-and-publish-js.yaml) (中文(简体) ).
触发 : 推动 master 变动情况 javascript/ (仅运行于 copilot-widget) (中文(简体) ).
步骤 :
- 安装依赖关系
- 运行测试( R)
npm run test(中文(简体) ) - 构建( E)
npm run build(中文(简体) ) - 发布到 npm (
npm publish --access public(中文(简体) ) - 将UMD捆绑和CSS上传到Google Cloud存储桶,用于CDN的发件,由软件包版本提供:
<bucket>/copilot-widget/<version>/*.umd.js <bucket>/copilot-widget/<version>/*.css
创建共线
对照本地版本的 SDK 依赖性开发, 使用 npm link数字 :
副驾驶
# In javascript/copilot-sdk
npm install
npm run build
npm link
# In javascript/copilot-widget
npm link @cimulate/copilot-sdk
代理服务器
# In javascript/agentforce-sdk
npm install
npm run build
npm link
# In javascript/copilot-widget
npm link @cimulate/agentforce-sdk
打开并恢复登记版本:
npm unlink @cimulate/copilot-sdk
npm unlink @cimulate/agentforce-sdk
npm install