@crh-fe/oava-customer-sdk

数字人视频见证 / 自助视频 双录访客端 SDK

由 widget 工程构建产出，对应源码 widget/lib/customerIndex.js。

包名：@crh-fe/oava-customer-sdk · 入口：dist/customerComponent.js

一、特性

• 基于 React + WebRTC 的访客端视频组件，支持数字人坐席和真人坐席两种模式
• 一行 new 即可创建实例，自带 TURN/媒体协商、推流、订阅
• 提供人脸在框检测、等待超时、转人工等业务事件回调
• ES Module 包，type: "module"，浏览器原生或 webpack 5 均可消费

二、安装

1. 从内部 npm 源安装（推荐）

npm install @crh-fe/oava-customer-sdk

2. 本地 tarball 安装

仓库内已打好包：

npm install ./packages/customer-sdk/oava-customer-sdk-1.0.1.tgz

3. 通过 public/ 静态文件直接引用（不推荐，仅用于本地调试）

把 widget/output/customerComponent.js 拷到消费者工程的 public/ 目录，然后用 <script> 标签引入，会挂载在 window.CustomerComponent（default export）。客户 demo demo/customer-demo/src/components/Home.vue 同时支持这两种方式的在线切换。

三、快速开始

import Customer from "@crh-fe/oava-customer-sdk";

// 1. 实例化，传入 TURN 服务地址
const client = new Customer("turn:49.234.13.99?transport=udp");

// 2. 监听会话结束事件（必接）
client.onEnd((e) => {
  // e.code 参考下方【事件码表】
  console.log("会话结束", e);
  client.destroy();
});

// 3. 初始化挂载。id 为空时挂到 body，否则挂到指定容器
client.init("", {
  roomToken: "后端派单接口返回的 roomToken",
  aiServerUrl: "https://your-face-detect-server.com",
  faceCheckTimer: 3000,   // 人脸在框检测间隔，单位 ms，默认 2000
  maxWaitTime: 120,       // 等待数字人/真人接入超时，单位 s，默认 120
  userFaceBase64: "...",  // 可选，用户人脸 base64，做人像比对
});

四、API 参考

4.1 new CustomerComponent(turnServerUrl)

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | turnServerUrl | string | 否 | IRTC 媒体平台 TURN 地址，默认 turn:106.15.227.129:3478?transport=udp |

构造函数会在控制台输出：

[SDK Version] v1.0.1
[SDK version] v1.0.1, turnServerUrl: <传入值>

4.2 init(id, options)

挂载并启动组件。

| 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | id | string | 否 | 容器 DOM 的 id；传空字符串时挂载到 body，会动态创建一个 position: fixed; inset: 0; 的全屏容器，组件卸载时自动移除 | | options | object | 是 | 见下表 |

options 字段

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | roomToken | string | 是 | 房间 token，由后端 /tokens 或派单接口下发 | | aiServerUrl | string | 是 | 人脸在框检测服务地址 | | faceCheckTimer | number | 否 | 人脸在框检测间隔，单位 ms，默认 2000 | | maxWaitTime | number | 否 | 等待数字人/真人接入的最大时长，单位 s，默认 120 | | userFaceBase64 | string | 否 | 用户人脸 base64，用于人像比对 |

4.3 destroy()

销毁组件、断开 WebRTC 推拉流、卸载 React 树，并自动移除由 init("", ...) 创建的 customer-component-container-id 容器。一次会话结束务必调用，否则下次 new 会残留 DOM。

4.4 onEnd(callback)

注册会话结束回调，只能触发一次，触发后回调被置空。回调参数：

type EndCallbackParams = {
  code: string;        // 状态码，见下表
  message: string;     // 描述
  data?: any;          // 业务数据
  type?: string;       // 自定义事件类型
  reason?: string;     // 主动离开时的原因
};

事件码表

| code | 含义 | | --- | --- | | 300 | 见证通过 | | 301 | 见证不通过 | | 400 | 用户自己主动离开 | | 401 | 用户自己主动离开，去自助视频 | | 6001 | 加入房间失败 | | 6002 | 创建本地摄像头失败 | | 6003 | 本地推流异常中断 | | 6004 | 推送本地画面失败 | | 6005 | 订阅数字人画面失败 | | 6008 | 数字人流结束 | | 7000 | 服务异常 | | 7002 | 数字人坐席离开 | | 8001 | 等待数字人接入超时 | | 8002 | 等待真人坐席接入超时 |

转人工（transfer）期间，坐席相关的 6001/7002 等事件会被抑制，不再触发 onEnd，直到 cancel-transfer 复位。

五、完整示例（客户 demo）

demo/customer-demo/src/components/Home.vue 里的最小闭环：

import Customer from "@crh-fe/oava-customer-sdk";

// 1. 加入排队
const queueRes = await request({
  url: `${aiUrl}/auditcenter/authless/openapi/video/joinQueue`,
  data: { task_id: taskId },
});

// 2. 轮询排队结果，坐席接入后拿到 roomToken
const queryRes = await request({
  url: `${aiUrl}/auditcenter/authless/openapi/video/queryQueue`,
  data: { task_id: taskId },
});
const { room_id, room_token } = JSON.parse(queryRes.data.json_params);

const tokenRes = await request({
  url: "https://zmscrh.zealcomm.cn/tokens",
  data: { room: room_id, user: "testuser", role: "presenter", domain: "public" },
});

// 3. 实例化 SDK 并启动
const client = new Customer("turn:49.234.13.99?transport=udp");

client.onEnd((e) => {
  if (e.code == "300") showSuccess();         // 见证通过
  else if (e.code == "301") showFail();        // 见证不通过
  else if (e.code == "200") return;            // 收到转人工，不结束
  else queryAuditResult();                     // 其它码：查后端审核结果
  client.destroy();
});

client.init("", {
  roomToken: tokenRes,                                // 派单接口下发的 roomToken
  aiServerUrl: "https://cpekh.test.cairenhui.com",   // 人脸在框检测
  faceCheckTimer: 300000,
  maxWaitTime: 10000,
});

六、构建与发布

6.1 本地构建

回到 widget/ 根目录：

# 产出 output/customerComponent.js 并同步到本 package 的 dist/
npm run build:npm:customer

它会按顺序执行：

1. npm run build — rollup 打包
2. npm run sanitize:customer — 去除 bundle 中残留的 propTypes 警告链接等
3. npm run sync:customer-package — 把产物拷到 packages/customer-sdk/dist/

6.2 打包 tgz

cd packages/customer-sdk
npm pack  # 产出 oava-customer-sdk-<version>.tgz

仓库内已附 oava-customer-sdk-1.0.1.tgz，可直接 npm install 本地引用。

6.3 发布到 npm

cd packages/customer-sdk
npm publish
npm publish --access public
# 私有源：npm publish --registry=https://your-private-registry/

发布前确认：

• packages/customer-sdk/package.json 里的 name 已改成你想要的 scope（当前为 @crh-fe/oava-customer-sdk）
• version 字段按语义化版本号递增
• dist/customerComponent.js 是最新构建产物

七、注意事项

1. 包体积约 2.8 MB（含 React/ReactDOM/IRT 媒体 SDK/业务组件），首次加载建议走 CDN 或拆 chunk 懒加载。
2. 纯 ESM 包（type: "module"）：webpack 4 / 旧版 vue-cli 默认走 CJS interop 会拿不到 default，请升级到 webpack 5 / vue-cli ≥ 5，或按需使用 import("@crh-fe/oava-customer-sdk") 动态导入。
3. 必须先 npm install：项目依赖里要显式声明 @crh-fe/oava-customer-sdk，否则构建/运行会报模块未找到。
4. TURN 地址要可访问：构造器里的 TURN 服务必须与生产/测试环境媒体平台对齐，否则视频流不通。
5. onEnd 仅触发一次：会话结束、收到见证结论、转人工之外的超时/异常都会触发，记得在回调里调用 client.destroy() 释放资源。
6. 来源切换（仅在 demo 中需要）：demo 同时演示了
   • 本地静态文件 public/customerComponent.js（适合 SDK 还没发布时的联调）
   • npm 包 @crh-fe/oava-customer-sdk（适合已发布后回归验证） 切换时务必先 destroy() 旧实例，避免 DOM/媒体通道残留。