humanchat-sdk 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -0
- package/demo.html +1 -0
- package/img/keyboardbtn1.77a3341c.svg +9 -0
- package/img/sendbtn1.4e0d0ce0.svg +9 -0
- package/img/stopbtn1.cbc7385c.svg +9 -0
- package/img/viocebtn1.34343bdc.svg +6 -0
- package/index.common.js +47685 -0
- package/index.common.js.map +1 -0
- package/index.css +1 -0
- package/index.umd.js +47698 -0
- package/index.umd.js.map +1 -0
- package/index.umd.min.js +28 -0
- package/index.umd.min.js.map +1 -0
- package/package.json +20 -0
package/README.md
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
```markdown
|
|
2
|
+
# NJBDB 数字人集成文档（SDK + iframe）
|
|
3
|
+
|
|
4
|
+
> 1. **SDK 方式**（推荐）：功能全、体验优，支持 H5、微信小程序、支付宝小程序。
|
|
5
|
+
> 2. **iframe 方式**（轻量）：零开发、三步嵌入，仅支持 H5。
|
|
6
|
+
> 如无特殊限制，请优先使用 SDK。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 目录
|
|
11
|
+
1. 快速选型
|
|
12
|
+
2. SDK 接入（H5 / 小程序）
|
|
13
|
+
2.1 安装与初始化
|
|
14
|
+
2.2 常用 API
|
|
15
|
+
2.3 事件回调
|
|
16
|
+
2.4 最佳实践
|
|
17
|
+
3. iframe 接入（纯 H5）
|
|
18
|
+
3.1 获取嵌入地址
|
|
19
|
+
3.2 完整代码示例
|
|
20
|
+
3.3 跨域与通信
|
|
21
|
+
4. 常见问题（SDK & iframe 通用）
|
|
22
|
+
5. 更新日志
|
|
23
|
+
6. 技术支持
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 1. 快速选型
|
|
28
|
+
| 维度 | SDK | iframe |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| 支持平台 | H5 + 微信小程序 + 支付宝小程序 | 仅 H5 |
|
|
31
|
+
| 功能完整性 | 全部能力（麦克风、波形、外部大脑、样式自定义） | 仅播报 + 简单问答 |
|
|
32
|
+
| 接入成本 | 需 npm 安装 + 5 行代码初始化 | 复制 1 段 iframe 即可 |
|
|
33
|
+
| 适用场景 | 正式业务、品牌交付、复杂交互 | 活动页、demo、临时页面 |
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 2. SDK 接入（H5 / 小程序）
|
|
39
|
+
|
|
40
|
+
### 2.1 安装与初始化
|
|
41
|
+
```bash
|
|
42
|
+
# 1. 安装（推荐 npm）
|
|
43
|
+
npm i humanchat-sdk --save
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<!-- 2. 准备容器（H5 示例） -->
|
|
48
|
+
<div id="dh-box" style="width:320px;height:540px;margin:0 auto;"></div>
|
|
49
|
+
<div id="wave-box" style="width:300px;height:60px;margin:10px auto;"></div>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
// 3. 初始化
|
|
54
|
+
import 'humanchat-sdk/index.css';
|
|
55
|
+
import XmenAI from 'humanchat-sdk';
|
|
56
|
+
|
|
57
|
+
const dh = new XmenAI({
|
|
58
|
+
token: 'YOUR_TOKEN', // 商务获取
|
|
59
|
+
projectId: 'YOUR_PROJECT_ID', // 亿话平台「项目管理」页复制
|
|
60
|
+
container: document.getElementById('dh-box'),
|
|
61
|
+
width: 320,
|
|
62
|
+
height: 540,
|
|
63
|
+
microphone: true, // 需要麦克风问答
|
|
64
|
+
wave: document.getElementById('wave-box'),
|
|
65
|
+
isUseChat: true, // 使用外部大脑
|
|
66
|
+
insertAiAnswer: false, // 隐藏内置输入框
|
|
67
|
+
onInitComplete: () => {
|
|
68
|
+
dh.speak('数字人初始化完成！', true, true);
|
|
69
|
+
},
|
|
70
|
+
onStartTalking: () => {
|
|
71
|
+
// 开始说话
|
|
72
|
+
},
|
|
73
|
+
onEndTalking: () => {
|
|
74
|
+
// 结束说话
|
|
75
|
+
},
|
|
76
|
+
onUpperLimit: () => {
|
|
77
|
+
// 并发达到上限或者高级口型未加载完成无法问答
|
|
78
|
+
},
|
|
79
|
+
onReceivedTheIssue: (question) => {
|
|
80
|
+
// 调用你的大模型接口
|
|
81
|
+
fetch('/api/chat', { method: 'POST', body: JSON.stringify({ q: question }) })
|
|
82
|
+
.then(r => r.json())
|
|
83
|
+
.then(res => dh.speak(res.answer, true, true));
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**小程序仅需把 `container` 换成 `this.selectComponent('#dh-box')`，其余完全一致。**
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
### 2.2 常用 API
|
|
93
|
+
| 方法 | 说明 | 示例 |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `speak(text, begin, finish)` | 触发播报 | 见上 |
|
|
96
|
+
| `stopSpeak()` | 立即停止当前播报 | `dh.stopSpeak()` |
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
### 2.3 最佳实践
|
|
101
|
+
1. **HTTPS 环境**才能开启麦克风；小程序需在 `app.json` 声明 `record` 权限。
|
|
102
|
+
2. **长文本分段播报**：每段 ≤ 120 字，用户体验更自然。
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 3. iframe 接入（纯 H5）
|
|
107
|
+
|
|
108
|
+
> 3 步完成：① 创建项目 → ② 复制链接 → ③ 粘贴 iframe
|
|
109
|
+
|
|
110
|
+
### 3.1 获取嵌入地址
|
|
111
|
+
1. 登录 [亿话平台](https://yh.bdbdigital.com) → 创建项目 → 发布
|
|
112
|
+
2. 在「发布成功」弹窗里点「复制链接」
|
|
113
|
+
3. 在 URL 后拼接参数（可组合）：
|
|
114
|
+
|
|
115
|
+
| 参数 | 含义 | 示例 |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| `isNesting=true` | 必须，背景透明 | …&isNesting=true |
|
|
118
|
+
| `insertAiAnswer=true` | 显示内置问答输入框 | …&insertAiAnswer=true |
|
|
119
|
+
| `isUseChat=true` | 使用外部大脑 | …&isUseChat=true |
|
|
120
|
+
| `isShowRecordList=true` | 显示聊天记录 | …&isShowRecordList=true |
|
|
121
|
+
|
|
122
|
+
**最终示例地址**
|
|
123
|
+
`https://dev.bdbdigital.com/preview2d?id=egGXsD&isNesting=true&insertAiAnswer=true&isUseChat=true&isShowRecordList=true`
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
### 3.2 完整代码示例
|
|
128
|
+
```html
|
|
129
|
+
<!-- 1. 嵌入数字人 -->
|
|
130
|
+
<iframe id="myIframe"
|
|
131
|
+
src="https://dev.bdbdigital.com/preview2d?id=egGXsD&isNesting=true&insertAiAnswer=true&isUseChat=true&isShowRecordList=true"
|
|
132
|
+
frameborder="0"
|
|
133
|
+
style="width:320px;height:540px;margin:0 auto;display:block;">
|
|
134
|
+
</iframe>
|
|
135
|
+
|
|
136
|
+
<script>
|
|
137
|
+
// 2. 监听数字人发来的问题
|
|
138
|
+
window.addEventListener('message', e => {
|
|
139
|
+
if (e.data.type === 'question') {
|
|
140
|
+
const userQuestion = e.data.value;
|
|
141
|
+
// 调用你的接口
|
|
142
|
+
fetch('/api/chat', { method: 'POST', body: JSON.stringify({ q: userQuestion }) })
|
|
143
|
+
.then(r => r.json())
|
|
144
|
+
.then(res => {
|
|
145
|
+
// 3. 把答案回传数字人
|
|
146
|
+
document.getElementById('myIframe').contentWindow.postMessage({
|
|
147
|
+
answer: res.answer, // 播报文本
|
|
148
|
+
begin_sign: true, // 第一句
|
|
149
|
+
finish: true // 最后一句
|
|
150
|
+
}, '*');
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
});
|
|
154
|
+
</script>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
### 3.3 跨域与通信
|
|
160
|
+
- 接入方后台 **必须配置 CORS**，允许 `https://dev.bdbdigital.com` 跨域调用。
|
|
161
|
+
- 仅支持 **单向问答**（用户问→接口答→数字人播），暂不支持连续多轮。
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## 4. 常见问题（通用）
|
|
166
|
+
| 问题 | 排查要点 |
|
|
167
|
+
|---|---|
|
|
168
|
+
| 初始化报 “token 无效” | 确认 token 与 projectId 在亿话平台「已启用」 |
|
|
169
|
+
| 麦克风无权限 | HTTPS / 小程序声明 / 用户授权 |
|
|
170
|
+
| 调用 speak 无反应 | 是否触发 `onInitComplete`；是否触发 `onUpperLimit` |
|
|
171
|
+
| iframe 收不到消息 | 检查是否 HTTPS；后台是否放行跨域 |
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## 5. 更新日志
|
|
176
|
+
| 版本 | 日期 | 说明 |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| v1.0.0 | 2025-09-11 | 合并 SDK + iframe 双文档；首次发布 |
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 6. 技术支持
|
|
183
|
+
- 商务 / Token 申请 / 技术咨询
|
|
184
|
+
📧 15121129113@163.com
|
|
185
|
+
📞 15121129113（工作日 9:30-18:30）
|
|
186
|
+
|
|
187
|
+
> 文档如有未尽，欢迎邮件或电话，我们 1 个工作日内响应。
|
|
188
|
+
```
|
package/demo.html
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<!doctype html><meta charset="utf-8"><title>index demo</title><script src="./index.umd.js"></script><link rel="stylesheet" href="./index.css"><script>console.log(index)</script>
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<path d="M8 5H6C4.89543 5 4 5.89543 4 7V9C4 10.1046 4.89543 11 6 11H8C9.10457 11 10 10.1046 10 9V7C10 5.89543 9.10457 5 8 5Z" fill="#595959"/>
|
|
3
|
+
<path d="M17 5H15C13.8954 5 13 5.89543 13 7V9C13 10.1046 13.8954 11 15 11H17C18.1046 11 19 10.1046 19 9V7C19 5.89543 18.1046 5 17 5Z" fill="#595959"/>
|
|
4
|
+
<path d="M26 5H24C22.8954 5 22 5.89543 22 7V9C22 10.1046 22.8954 11 24 11H26C27.1046 11 28 10.1046 28 9V7C28 5.89543 27.1046 5 26 5Z" fill="#595959"/>
|
|
5
|
+
<path d="M8 15H6C4.89543 15 4 15.8954 4 17V19C4 20.1046 4.89543 21 6 21H8C9.10457 21 10 20.1046 10 19V17C10 15.8954 9.10457 15 8 15Z" fill="#595959"/>
|
|
6
|
+
<path d="M17 15H15C13.8954 15 13 15.8954 13 17V19C13 20.1046 13.8954 21 15 21H17C18.1046 21 19 20.1046 19 19V17C19 15.8954 18.1046 15 17 15Z" fill="#595959"/>
|
|
7
|
+
<path d="M26 15H24C22.8954 15 22 15.8954 22 17V19C22 20.1046 22.8954 21 24 21H26C27.1046 21 28 20.1046 28 19V17C28 15.8954 27.1046 15 26 15Z" fill="#595959"/>
|
|
8
|
+
<path d="M29 25H3C2.44772 25 2 25.4477 2 26C2 26.5523 2.44772 27 3 27H29C29.5523 27 30 26.5523 30 26C30 25.4477 29.5523 25 29 25Z" fill="#595959"/>
|
|
9
|
+
</svg>
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<path d="M27.6017 4.95468L22.6817 27.9878C22.6548 28.1152 22.5969 28.234 22.5133 28.3338C22.4296 28.4335 22.3227 28.5111 22.202 28.5598C22.0815 28.6079 21.9509 28.6252 21.8221 28.6101C21.6932 28.5951 21.5701 28.5482 21.464 28.4737L19.1255 26.8534C17.3139 25.5982 14.9278 25.546 13.0631 26.7208C12.9377 26.8081 12.7897 26.857 12.6371 26.8616C12.4844 26.8662 12.3338 26.8263 12.2034 26.7468C12.073 26.6673 11.9686 26.5515 11.9028 26.4137C11.8371 26.2759 11.8128 26.1219 11.8331 25.9705L12.2759 21.5484C12.2868 21.3911 12.3495 21.2419 12.4542 21.124L18.3767 13.9588L11.5342 20.3055C11.2343 20.5837 10.9842 20.9768 10.5829 21.0563C10.3789 21.0966 10.1673 21.0546 9.99421 20.9395L3.35221 16.5174C3.23669 16.4408 3.14344 16.335 3.08188 16.2108C3.02033 16.0867 2.99266 15.9484 3.00166 15.8101C3.01244 15.6707 3.05957 15.5366 3.13834 15.4211C3.21712 15.3057 3.32479 15.2129 3.45061 15.152L26.4701 4.08133C26.6024 4.01568 26.7507 3.98893 26.8976 4.00417C27.0446 4.01941 27.1842 4.07602 27.3003 4.16744C27.4183 4.25804 27.5089 4.37955 27.5621 4.5185C27.6153 4.65746 27.629 4.80843 27.6017 4.95468Z" fill="url(#paint0_linear_18_2215)"/>
|
|
3
|
+
<defs>
|
|
4
|
+
<linearGradient id="paint0_linear_18_2215" x1="3" y1="16.3077" x2="27.6154" y2="16.3077" gradientUnits="userSpaceOnUse">
|
|
5
|
+
<stop stop-color="#7B4AFF"/>
|
|
6
|
+
<stop offset="1" stop-color="#2991F1"/>
|
|
7
|
+
</linearGradient>
|
|
8
|
+
</defs>
|
|
9
|
+
</svg>
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<path d="M16 2C23.732 2 30 8.26801 30 16C30 23.732 23.732 30 16 30C8.26801 30 2 23.732 2 16C2 8.26801 8.26801 2 16 2ZM16 4C9.37258 4 4 9.37258 4 16C4 22.6274 9.37258 28 16 28C22.6274 28 28 22.6274 28 16C28 9.37258 22.6274 4 16 4ZM18 12C19.1046 12 20 12.8954 20 14V18C20 19.1046 19.1046 20 18 20H14C12.8954 20 12 19.1046 12 18V14C12 12.8954 12.8954 12 14 12H18Z" fill="url(#paint0_linear_2164_2712)"/>
|
|
3
|
+
<defs>
|
|
4
|
+
<linearGradient id="paint0_linear_2164_2712" x1="2" y1="16" x2="30" y2="16" gradientUnits="userSpaceOnUse">
|
|
5
|
+
<stop stop-color="#7B4AFF"/>
|
|
6
|
+
<stop offset="1" stop-color="#2991F1"/>
|
|
7
|
+
</linearGradient>
|
|
8
|
+
</defs>
|
|
9
|
+
</svg>
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
<svg width="41" height="32" viewBox="0 0 41 32" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<rect x="11.7273" y="1.72729" width="8.54545" height="18.5455" rx="4.27273" fill="#595959" stroke="#595959" stroke-width="1.45455"/>
|
|
3
|
+
<path d="M8 14V16.1818C8 20.6001 11.5817 24.1818 16 24.1818V24.1818C20.4183 24.1818 24 20.6001 24 16.1818V14" stroke="#595959" stroke-width="2" stroke-linecap="round"/>
|
|
4
|
+
<rect x="15" y="24" width="2" height="7" rx="1" fill="#595959"/>
|
|
5
|
+
<path d="M40 8L40 24" stroke="#BFBFBF" stroke-linecap="round"/>
|
|
6
|
+
</svg>
|