演化聊天部件

Evolve 电子商务平台可嵌入聊天部件 。 允许客户在您的网站上直接与AI购物助理互动.

特征

• 浮动按钮或内嵌模式
• 有图像、价格和数量的产品卡
• 购物车和愿望名单整合
• 可配置品牌和标签
• 从 JWT 自动提取用户名
• 使用共享饼干的跨源支持

安装

脚本标记( 最轻松)

将部件脚本添加到您的 HTML 中 :

<script src="https://chat.evolve-platform.com/widget.js"></script>
<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'floating',
    position: { horizontal: 'right', vertical: 'bottom' },
  });
</script>

pnpm 软件包

pnpm install @evolve-packages/chat-widget

import { EvolveChatWidget } from '@evolve-platform/chat-widget';

function App() {
  return (
    <EvolveChatWidget
      tenantId="evolve"
      mode="floating"
      branding={{ primaryColor: '#f97316' }}
    />
  );
}

配置

需要的选项

显示选项

位置配置

interface WidgetPosition {
  horizontal: 'left' | 'right';  // default: 'right'
  vertical: 'top' | 'bottom';    // default: 'bottom'
  offsetX?: number;              // default: 20
  offsetY?: number;              // default: 20
}

标记选项

interface WidgetBranding {
  primaryColor?: string;      // Primary color (default: '#f97316')
  primaryTextColor?: string;  // Text on primary (default: '#ffffff')
  accentColor?: string;       // Call-to-action colour (default: primaryColor)
  accentTextColor?: string;   // Text on accent (default: primaryTextColor)
  headerTitle?: string;       // Widget header title
  logoUrl?: string;           // Custom logo URL
  avatarUrl?: string;         // Avatar for assistant messages
  showHeader?: boolean;       // Inline only: header bar with logo and title (default: true)
}

标签选项

interface WidgetLabels {
  placeholder?: string;  // Input placeholder text
  greeting?: string;     // Greeting message (use {name} for user name)
  thinking?: string;     // "Thinking" indicator text
  close?: string;        // Close button label
  sendLabel?: string;    // Accessible name of the send button (default: 'Send message')
}

背景选项

回电

interface WidgetCallbacks {
  onOpen?: () => void;              // Called when widget opens
  onClose?: () => void;             // Called when widget closes
  onMessage?: (message: string) => void;  // Called when user sends message
  onError?: (error: Error) => void; // Called on error
}

项目助理

项目助理是一个选入功能,可以使后端的项目协助工具转出(ask_user, (中文(简体) ), select_product, (中文(简体) ), present_kit, (中文(简体) ), offer_help,.)入交互式卡:问牌,出品道,有推车/列表动作的材料列表,手动链接联系表,快速启动屏幕和进度栏.

<EvolveChatWidget
  tenantId="evolve"
  features={["projectAssistant"]}
  isAuthenticated={isLoggedIn}
  labels={{
    projectAssistant: {
      quickStartJobs: [
        { id: "roof", emoji: "🏠", title: "Solar panels on a roof", prompt: "I want to install solar panels on my roof" },
      ],
      questSteps: ["Roof", "Panels", "Inverter", "Materials list"],
    },
  }}
/>

• features={["projectAssistant"]} 打开特性;没有它,部件将像以前一样使这些工具生效. WidgetFeatureId 用于输入列表.
• isAuthenticated 决定提供哪些材料列表动作:签名的购物者获得"添加来推"和"保存为列表",匿名购物者仅获得"共享列表".
• loadShoppingLists (可选, () => Promise<WidgetShoppingList[]>,每个 { id, version, name }) 将被签入的"拯救为列表"变成最爱的菜单. 部件每次打开菜单时都会调用它, 并且从不获取列表本身, 因此主机会用自己的会话加载它们 。 选择列表发送 save_list 与该列表 listId 财务报告和审定财务报表 version; "新共享列表"发送时没有 listId。没有回电,"保存为列表"发送 save_list 直去如来所.
• createShoppingList (可选, (name: string) => Promise<WidgetShoppingList>)在该菜单中放出"新列表"而不是"新可共享列表":shopper输入一个名称,主机用自己的会话创建客户账户中的列表并返回 { id, version, name },然后部件发送 save_list 与那个 listId 财务报告和审定财务报表 version。被拒绝的许诺会打开菜单 receiptNewListError。没有它,菜单会保留匿名的“新共享列表”.
• labels.projectAssistant (单位:千美元)ProjectAssistantLabels)覆盖任何副本。 包件一般默认,没有目录内容,所以主机用品 quickStartJobs (在空状态上; prompt 以第一句话发出)和 questSteps (进度栏;其名称必须与 questStep 值值后端工具会出。 留空会隐藏元素 .
• 何时 quickStartJobs 是非空的,快速启动屏幕将替换主机 greeting 在空闲聊天中。 它显示 quickStartTitle, (中文(简体) ), quickStartSubtitle, (中文(简体) ), quickStartQuestion,工作牌和 quickStartHint;一个空字符串会隐藏任何文本.
• 虽然其特性是活性的,作曲者是一个有圆形发送按钮的大圆形场. branding.primaryColor 驱动脚步器、链接、瓦片边框、牌头条和发泡条; branding.accentColor 驱动调用动作:发送按钮,收件的第一个动作和帮助提供的联系按钮,次要收件动作以主色调来概述. 没有口音,两者都回到了主色调. 两者皆可能是CSS变量,例如 var(--brand-main)。 。 。 .
• 聊天可以通过的页名 branding={{ showHeader: false }} 内入模式中;然后部件也会降低其卡片阴影和半径,从而使主机容器框框中它.

后端合同

工程助理卡发送的每个回答都是普通用户信息,其文本为JSON对象带有一个 pa_action 字段。 后端系统提示必须理解这六个动作:

部件将这些消息显示为短徽而非生 JSON.

AI SDK 版本

部件运行于AI SDK 7. 以 AI SDK 7 为基础的聊天后端发布 toolMetadata 转到旧部件拒绝的 MCP 工具块,因此将这个软件包与 @evolve-framework/chat-backend (ai-7释放)。 部件仍然从 AI SDK 6 后端剖析流出 .

实例

浮动部件( 右下方)

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'right',
    vertical: 'bottom',
    offsetX: 20,
    offsetY: 20,
  },
  branding: {
    primaryColor: '#f97316',
  },
});

浮动部件( 从下到左)

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'left',
    vertical: 'bottom',
  },
});

内嵌

<div id="chat-container" style="width: 400px; height: 600px;"></div>

<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'inline',
    container: '#chat-container',
  });
</script>

用 Cart 整合

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  cartId: 'abc123-cart-id',
  firstName: 'Jan',
});

自定义品牌

EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  branding: {
    primaryColor: '#1e40af',
    primaryTextColor: '#ffffff',
    headerTitle: 'Shop Assistant',
  },
  labels: {
    placeholder: 'Stel je vraag...',
    greeting: 'Hoi {name}! Hoe kan ik je helpen?',
    thinking: 'Even denken...',
  },
});

发展

构建

pnpm run build

产出:

• dist/widget.js - UMD 捆绑(用于脚本标记,包括反应)
• dist/widget.css - 被提取的样式
• dist/index.esm.js - 无害环境管理捆绑(用于pnpm,作为对等处理)
• dist/index.js - CJS 捆绑(用于 pnpm, 反应为 pal dep)

发展模式

pnpm run dev     # Watch mode with auto-rebuild
pnpm run serve   # Serve dist folder for testing

类型检查

pnpm run typecheck

建筑

widget/
├── src/
│   ├── index.ts              # pnpm package entry
│   ├── init.ts               # Script tag entry (EvolveChat.init)
│   ├── components/
│   │   ├── ChatWidget.tsx    # Main wrapper
│   │   ├── FloatingButton.tsx
│   │   ├── ChatPanel.tsx
│   │   ├── WidgetChat.tsx    # Chat UI (no Next.js deps)
│   │   ├── WidgetProductCard.tsx
│   │   └── WidgetToolQuery.tsx
│   ├── context/
│   │   └── WidgetProvider.tsx
│   ├── styles/
│   │   └── widget.css
│   ├── types/
│   │   └── config.ts
│   └── utils/
│       ├── api.ts
│       └── graphql-product-mapper.ts
├── dist/                     # Build output
├── package.json
├── rollup.config.js
└── tsconfig.json

Cookie 需求

要进行跨域认证,必须配置 cookie :

1. Cookie 域名数字 : .evolve-platform.com (子域有主点)
2. 同一地点数字 : Lax 或者说 None (与 Secure 旗帜)
3. (简体中文): 服务器必须发送 Access-Control-Allow-Credentials: true

浏览器支持

• 克罗姆80+
• Firefox 75+ (英语)
• 萨法里13+
• 边80+

许可证

麻省理工学院