humanchat-sdk

# 数字人集成文档（SDK + iframe）

> 1. **SDK 方式**（推荐）：功能全、体验优，支持 H5、微信小程序、支付宝小程序。  
> 2. **iframe 方式**（轻量）：零开发、三步嵌入，仅支持 H5。  
> 如无特殊限制，请优先使用 SDK。

---

## 目录
1. 快速选型  
2. SDK 接入（H5 / 小程序）  
   2.1 安装与初始化  
   2.2 常用 API  
   2.3 事件回调  
   2.4 最佳实践  
3. iframe 接入（纯 H5）  
   3.1 获取嵌入地址  
   3.2 完整代码示例  
   3.3 跨域与通信  
4. 常见问题（SDK & iframe 通用）  
5. 更新日志  
6. 技术支持  

---

## 1. 快速选型
| 维度 | SDK | iframe |
|---|---|---|
| 支持平台 | H5 + 微信小程序 + 支付宝小程序 | 仅 H5 |
| 功能完整性 | 全部能力（麦克风、波形、外部大脑、样式自定义） | 仅播报 + 简单问答 |
| 接入成本 | 需 npm 安装 + 5 行代码初始化 | 复制 1 段 iframe 即可 |
| 适用场景 | 正式业务、品牌交付、复杂交互 | 活动页、demo、临时页面 |


---

## 2. SDK 接入（H5 / 小程序）

### 2.1 安装与初始化
```bash
# 1. 安装（推荐 npm）
npm i humanchat-sdk --save

<!-- 2. 准备容器（H5 示例） -->
<div id="dh-box" style="width:320px;height:540px;margin:0 auto;"></div>
<div id="wave-box" style="width:300px;height:60px;margin:10px auto;"></div>

// 3. 初始化
import 'humanchat-sdk/index.css';
import XmenAI from 'humanchat-sdk';

const dh = new XmenAI({
  token: 'YOUR_TOKEN',          // 商务获取
  projectId: 'YOUR_PROJECT_ID', // 数字人AI智能体创作平台「项目管理」页复制
  container: document.getElementById('dh-box'),
  width: 320,
  height: 540,
  microphone: true,             // 需要麦克风问答
  wave: document.getElementById('wave-box'),
  isUseChat: true,              // 使用外部大脑
  insertAiAnswer: false,        // 隐藏内置输入框
  onInitComplete: () => {
    setTimeout(() => {
      dh.speak('数字人初始化完成！', true, true);
    })
  },
  onStartTalking: () => {
    // 开始说话
  },
  onEndTalking: () => {
    // 结束说话
  },
  onUpperLimit: () => {
    // 并发达到上限或者高级口型未加载完成无法问答
  },
  onReceivedTheIssue: (question) => {
    // 调用你的大模型接口
    fetch('/api/chat', { method: 'POST', body: JSON.stringify({ q: question }) })
      .then(r => r.json())
      .then(res => dh.speak(res.answer, true, true));
  }
});

小程序仅需把 container 换成 this.selectComponent('#dh-box')，其余完全一致。

2.2 常用 API

方法	说明	示例
speak(text, begin, finish)	触发播报	见上
stopSpeak()	立即停止当前播报	dh.stopSpeak()

2.3 最佳实践

• HTTPS 环境才能开启麦克风；小程序需在 app.json 声明 record 权限。
• 长文本分段播报：每段 ≤ 120 字，用户体验更自然。

3. iframe 接入（纯 H5）

3 步完成：① 创建项目 → ② 复制链接 → ③ 粘贴 iframe

3.1 获取嵌入地址

• 登录 数字人AI智能体平台 → 创建项目 → 发布
• 在「发布成功」弹窗里点「复制链接」
• 在 URL 后拼接参数（可组合）：

参数	含义	示例
isNesting=true	必须，背景透明	…&isNesting=true
insertAiAnswer=true	显示内置问答输入框	…&insertAiAnswer=true
isUseChat=true	使用外部大脑	…&isUseChat=true
isShowRecordList=true	显示聊天记录	…&isShowRecordList=true

最终示例地址
https://yh.ipavatar.com/yihuaVideoPreview?id=egGXsD&isNesting=true&insertAiAnswer=true&isUseChat=true&isShowRecordList=true

3.2 完整代码示例

<!-- 1. 嵌入数字人 -->
<iframe id="myIframe"
        src="https://yh.ipavatar.com/yihuaVideoPreview?id=egGXsD&isNesting=true&insertAiAnswer=true&isUseChat=true&isShowRecordList=true"
        frameborder="0"
        style="width:320px;height:540px;margin:0 auto;display:block;">
</iframe>

<script>
// 2. 监听数字人发来的问题
window.addEventListener('message', e => {
  if (e.data.type === 'question') {
    const userQuestion = e.data.value;
    // 调用你的接口
    fetch('/api/chat', { method: 'POST', body: JSON.stringify({ q: userQuestion }) })
      .then(r => r.json())
      .then(res => {
        // 3. 把答案回传数字人
        document.getElementById('myIframe').contentWindow.postMessage({
          answer: res.answer,   // 播报文本
          begin_sign: true,     // 第一句
          finish: true          // 最后一句
        }, '*');
      });
  }
});
</script>

3.3 跨域与通信

• 接入方后台 必须配置 CORS，允许 https://yh.ipavatar.com 跨域调用。
• 仅支持 单向问答（用户问→接口答→数字人播），暂不支持连续多轮。

4. 常见问题（通用）

问题	排查要点
初始化报 “token 无效”	确认 token 与 projectId 在数字人AI智能体平台「已启用」
麦克风无权限	HTTPS / 小程序声明 / 用户授权
调用 speak 无反应	是否触发 onInitComplete；是否触发 onUpperLimit
iframe 收不到消息	检查是否 HTTPS；后台是否放行跨域

5. 更新日志

版本	日期	说明
v1.0.0	2025-09-11	合并 SDK + iframe 双文档；首次发布

6. 技术支持

• 商务 / Token 申请 / 技术咨询
  📧 [e-mail]
  📞 15121129113（工作日 9:30-18:30）

文档如有未尽，欢迎邮件或电话，我们 1 个工作日内响应。