# @vocantly/widget 中文文档

规范地址：https://npmcn.com/package/%40vocantly/widget/

版本：0\.1\.26
npm 元数据更新时间：2026-11-02T20:28:01.058Z
中文译文更新时间：2026-11-02T20:37:46.371Z
软件包许可：UNLICENSED

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40vocantly/widget
原文对照：https://npmcn.com/package/%40vocantly/widget/?lang=original
项目主页：https://github.com/motiftechnology/vocantly-widget#readme
源码仓库：https://github.com/motiftechnology/vocantly-widget

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：705 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-09-25T20:51:39.463Z
- 最新版本发布：2026-11-02T20:28:00.888Z
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

插入式可嵌入支持聊天小部件为voctly，建立在@ voctly /sdk。

## 安装

```sh
npm install @vocantly/widget
```

也可以使用：`pnpm add @vocantly/widget`、`yarn add @vocantly/widget`、`bun add @vocantly/widget`

## README

# Vocantly小部件

一、 **可嵌入的支持聊天小部件** 建立在无头的基础上 `@vocantly/sdk`。一个 `<script>` 渲染一个浮动的聊天气泡+面板；你的访客与人工智能聊天 代理)与零UI工作在您这边。

`dist/vocantly-widget.js` 是一个独立的文件(~63 KB) - SDK，它的深度，和 UI都捆绑在一起。没有导入映射，没有主机的构建步骤。

## 安全模型（重要）

小部件在浏览器中运行，因此它只保存一个 **SDK令牌** (作用域为一个应用程序+一个 游客,短暂的)。你的 **API密钥+秘密永远不会触及浏览器。** 流:

```
Your backend (holds API key)                     Browser (this widget)
  POST /apps/:id/support-sessions   ── token + conversation_id ──▶  VocantlyWidget.init({...})
  (X-Api-Key + X-Api-Secret)
```

您的服务器调用供应端点，然后只执行手动操作 `{ token, conversation_id }` 到页面。

## 安装

**选项A -脚本标签（任何网站，通过CDN）：**

```html
<!-- unpkg / jsDelivr serve the bundled IIFE; global: VocantlyWidget -->
<script src="https://unpkg.com/@vocantly/widget"></script>
<!-- pin a version:  https://unpkg.com/@vocantly/widget@0.1.5 -->
```

**选项B - npm (React / Vue / Next / bundlers)：**

```bash
npm install @vocantly/widget
```

```js
import { init } from '@vocantly/widget';
init({ wsUrl, token, conversationId, /* … */ });
```

两者都提供了捆绑在零对等依赖中的SDK + deps。用法都是一样的：

```html
<script src="https://unpkg.com/@vocantly/widget"></script>
<script>
  VocantlyWidget.init({
    wsUrl: 'wss://your-realtime/ws',
    token: 'SDK_TOKEN_FROM_YOUR_BACKEND',
    conversationId: 'CONVERSATION_ID_FROM_YOUR_BACKEND',
    apiUrl: 'https://your-backend/api/v1',   // optional — enables message history
    title: 'Support',
    subtitle: 'We reply in a few minutes',
    primaryColor: '#195EFF',
    position: 'bottom-right',                // or 'bottom-left'
    greeting: 'Hi! 👋 How can we help?',
    autoOpen: false,

    // Optional pre-chat contact capture (needs apiUrl):
    collectContact: true,                    // ask name + email before chatting
    requireEmail: false,                     // if true, email is mandatory to start
    contactPrompt: 'Before we start — how can we reach you?',
  });
</script>
```

### 您的后端（对供应的一次调用）

```js
// server-side — keep the secret here
const r = await fetch(`${BASE}/apps/${APP_ID}/support-sessions`, {
  method: 'POST',
  headers: { 'X-Api-Key': PUBLIC_KEY, 'X-Api-Secret': SECRET_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ external_user_id: yourUserId, name, email }),
});
const { token, conversation_id } = (await r.json()).data;   // hand these to the browser
```

## 没有后端?只使用您的公钥匿名嵌入

对于一个静态的登陆页面 **未经身份验证的访问者和没有服务器**,使用 `publicKey` 而不是 `token`/`conversationId`。小部件自己提供一个匿名会话-在浏览器中没有秘密：

```html
<script src="https://unpkg.com/@vocantly/widget"></script>
<script>
  VocantlyWidget.init({
    publicKey: 'pk_…',                         // your app PUBLIC key (safe to expose)
    wsUrl:  'wss://ws.vocantly.com/ws',
    apiUrl: 'https://api.vocantly.com/api/v1',  // required in this mode
    collectContact: true,
  });
</script>
```

**一个先决条件-允许您的网站的来源。** 默认情况下，匿名嵌入是关闭的。添加你 域(s)应用程序的 `allowed_origins` （仪表板，或通过API）：

```bash
PATCH /apps/:id   { "allowed_origins": ["https://acme.com", "https://www.acme.com"] }
```

小部件生成 **稳定访客id** （localStorage）和缓存 `{token, conversationId}` 所以一个 重新加载将恢复相同的对话。请求在服务器端进行初始检查，并且速率有限。

> 提供 **要么** `publicKey` (匿名) **或者** `token` + `conversationId` (backend-provisioned)。

## API

| 呼叫 | 效果 |
| --- | --- |
| `VocantlyWidget.init(opts)` | Mount + connect。返回 `{ open, close, send, destroy }`. |
| `VocantlyWidget.open()` / `.close()` | 切换面板。 |
| `VocantlyWidget.destroy()` | 断开连接并从DOM中删除。 |

### 聊天前联系人捕获

与 `collectContact: true`时，小部件会询问访问者的姓名+（可选）电子邮件地址 聊天，并保存到他们的客户档案通过 `PATCH /sdk/customers/me` (经 SDK令牌-浏览器中没有秘密)。然后代理在收件箱中看到访问者的联系方式。 需要 `apiUrl` 待设置。使用 `requireEmail: true` 让电子邮件成为强制性的。

## 构建

```bash
npm run build       # → dist/vocantly-widget.js (minified IIFE, global VocantlyWidget)
npm run build:dev   # non-minified + sourcemap
```

构建包 `../vocantly-js-sdk/dist/index.js`。如果重新构建SDK，则重新构建小部件。

## 演示

```bash
npm run serve:demo   # serves this folder on :5173
# open http://localhost:5173/   (redirects to the demo)
```

> 避免端口Chrome块为“不安全”（例如5060 = SIP→） `ERR_UNSAFE_PORT`）. 5173很安全。 演示是一个模拟的业务页面。输入工作空间所有者的电子邮件/密码+ a **开发** 应用程序ID 并点击 **引导** -透过 `/apps/:id/support-sessions` (dev login代表你的 后端)并安装小部件。需要后端 `:3001`实时运行 `:8080`，和应用程序有 **启用bot +一个活跃的FAQ**.

## 已知的限制

Bot回复目前是实时交付的，但是 **不坚持** 服务器端，所以它们不会出现在 重新加载时的消息历史记录（客户/代理消息）。持久化bot消息是后端后续工作。

## 常见问题

### @vocantly/widget 是什么？

插入式可嵌入支持聊天小部件为voctly，建立在@ voctly /sdk。

### 如何安装 @vocantly/widget？

在项目目录运行 npm install @vocantly/widget，或使用 pnpm add / yarn add / bun add。

### @vocantly/widget 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @vocantly/widget 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @vocantly/widget 可以商用吗？

@vocantly/widget 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @vocantly/widget 还在维护吗？

最新版本 0\.1\.26 发布于 2026/11/03（今天）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。