调用炫彩活体相关API前需下载javascript SDK

# 下载地址

raw-jssdk-v2.0.3

下载后文件目录介绍：

├─ demo　　//主目录
　│　　├─html-demo　　//原生html/js方式引入sdk的demo
　│　　│　　├─index.html　//业务代码
　│　　│　　├─index.js　　//业务代码
　│　　├─react-demo　  //react demo 
　│　　
　├─ dist 　　
　 　　├─rtcsdk.min.js　　//raw炫彩sdk，使用umd方式打包，同时支持script标签，import/require
　 　　├─esm
　 　　　　├─rtcsdk.js  //使用esm方式打包，仅支持import方式

# 一、引入方式

# script标签引用

rtcsdk.min.js 使用umd方式打包

<script type='text/javascript' src="rtcsdk.min.js"></script>

# import或require方式引入

esm/rtcsdk.js 使用esm方式打包

# 二、api

# 实例化

初始化参数

let rtcVideo = new RctVideo({
	videoWrapper: 'videoWrapper', //页面中需要插入video元素的位置，为空的div标签，需要使用id属性
    host: 'wss://rtc-sgp.megvii.com', //服务地址，参考文档设置，为wss协议
	width: '100%', //video的宽，需填写单位px, rem, em;此宽高为video宽高，当video宽高与视频宽高不符合时，视频按照video宽高的最长边等比缩放，移动端视频为高大于宽，此配置可以以宽为基础，高度自适应。如用在pc端需自行处理
	height: 'auto', //video的高，需填写单位px, rem, em;
	token: 'xxxxxxx', //用户服务器端请求getToken返回的token,  getToken禁止使用前端调用，前端调用存在api_key泄漏风险
	videoPermsTimeout: '6000', //获取摄像头权限超时时间，毫秒，可为空
	webSocketTimeout: '6000', //WebSocket超时时间，毫秒，可为空
	WebRTCTimeout: '6000', //WebRTC链接超时时间，毫秒，可为空
	colorListener: (color, status, index, sum)=>{}, //传递color给用户，用户监听color变化，修改页面背景颜色
	tipListener: (tipCode, tipTxt)=>{}, //提示语信息
	statusListener: (statusCode)=>{}, //状态的改变，可对各个状态做相应处理（如处理加载中交互）、日志埋点等需求
	resultCallback: (isSuccess, resultCode, resultMessage)=>{}, //结果回调
	autoplayFailCallback: (play)=>{}，//视频无法自动播放时回调，需要在用户点击事件内触发play。可不传，为空时会默认覆盖一个播放按钮
})
rtcVideo.start()

# 回调参数说明

• colorListener(color, status, index, sum)

参数	说明
color	需要打光的16进制颜色，例：”#00FFFF“
status	RESET/DONE/COLORING。RESET：照镜子不通过。DONE：打光结束。COLORING：正在打光中
index	当前打光进度，例：1
sum	总打光数量，依赖于Raw-GetToken接口设置的color_number

• tipListener: (tipCode, tipTxt)

参数	说明
tipCode	提示信息码
tipTxt	默认提示信息文案

具体提示内容，随着服务升级错误可能会动态变化，除了FaceOK，其他错误不建议进行处理

tipCode	tipTxt
NoFaceFound	未发现人脸
InvalidFaceYaw	请正对摄像头
InvalidFacePitch	请正对摄像头
InvalidFaceEyeOcclusion	请露出眼睛
InvalidFaceMouth	请露出嘴巴
TooFarAwayFromCamera	请靠近摄像头
TooCloseFromCamera	请远离摄像头
InvalidFaceOutOfImage	请正视摄像头
InvalidFaceBrightness	请调节光线
FaceOK	请保持不动

• statusListener = (statusCode)

statusCode	说明
INIT_LOADING	初始化配置loading
INIT_LOADING_OVER	初始化配置loading状态结束
LOOK_MIRROR	照镜子阶段
SHOW_COLOR	打光阶段
RESULT_LOADING	打光结束等待返回结果loading
RESULT_LOADING_OVER	打光结束等待返回结果loading结束
DISCONNECTED	webrtc连接断开，需要强制刷新页面重新开始

• resultCallback = (isSuccess, resultCode, resultMessage)

isSuccess	说明
true	流程正常结束
false	流程中存在错误

resultCode	resultMessage	说明
1000	SUCCESS	流程正常结束
2000	DISCONNECTED	webrtc连接断开，需要用户特殊处理，弹窗提升网络断开，刷新页面
3000	TIMEOUT	检测流程超时，30秒，从建立连接完成开始计算。
4000	SUPPORT_ERROR	当前设备不支持炫彩活体：浏览器不支持webrtc,无法初始化
4000	PERMISSIONS_ERROR	当前设备不支持炫彩活体：浏览器无权限访问摄像头或用户拒绝，或6s内仍无法获取权限
4000	NETWORK_ERROR	当前设备不支持炫彩活体：建立webrtc连接后，6s内仍无法传输流
5000	TOKEN_EXPIRED	token超时/无效/已使用
5000	TOKEN_TIMES_EXCEEDED	token使用次数过多
5000	ILLEGAL_PARAMETER:{params}	初始化传入参数不合法，{}内为具体不合法参数

• autoplayFailCallback = (play)

play为播放方法。

# start

开始验证，此时才会唤起摄像头。并在id为videoWrapper的标签内插入video标签。

rtcVideo.start()

# destroy

主动销毁过程，会关闭webrtc，终止流程。在成功/失败回调中无需调用。videoWrapper标签内的video不会删除，需要手动删除，也可直接删除videoWrapper标签。在打光中销毁，会停留在当前打光颜色，需要自行处理。

rtcVideo.destroy()

# version

获取版本号

rtcVideo.version()

# 三、流程

主流程根据 statusListener 进行变更。INIT_LOADING、INIT_LOADING_OVER 为获取配置阶段。之后进入主要需要处理的流程。

1. 进入LOOK_MIRROR 照镜子阶段。检测人脸角度、光线是否符合检测标准。检测结果会实时触发tipListener，需要提示客户调整人脸。
2. LOOK_MIRROR 后会进入SHOW_COLOR阶段。此状态会触发colorListener，需要根据返回的颜色设置背景颜色。为了最大化通过率，打光阶段不可在页面设置其它元素，颜色范围设置为整个屏幕。在打光过程中也可能因为人脸质量下降导致打光中断，会触发statusListener，重新进入照镜子阶段（LOOK_MIRROR）。检测结束会进入RESULT_LOADING状态，等待验证结果。
3. RESULT_LOADING_OVER 结果返回，同时会触发 successCallback 。在 successCallback 内可通知服务端，调用get_result接口获取结果。
4. DISCONNECTED 为网络问题引起的连接中断，需要提示用户刷新页面，重新开始。

# 四、常见问题及解决方案

1. 需要使用https
2. 安卓，IOS 通过web-view使用需要进行一定的适配。方案如下：

安卓解决方案：https://blog.csdn.net/weixin_37939704/article/details/88554967

IOS解决方案： https://www.jianshu.com/p/e4452707e33a

# 打包后目录结构说明

├─ demo　　//主目录
　│　　├─html-demo　　//原生html/js方式引入sdk的demo
　│　　│　　├─index.html　//业务代码
　│　　│　　├─index.js　　//业务代码
　│　　├─react-demo　  //react demo 
　│　　
　├─ dist 　　
　 　　├─rtcsdk.min.js　　//raw炫彩sdk，同时支持script标签，import/require
　

# 五、更新日志

v2.0.3 2025年8月22日

• 变更：增加host配置（无默认值），支持其他地区服务

v2.0.2 2024年10月11日

• 变更：websocket ICE消息json结构变更

v2.0.1 2024年5月6日

• 增加：esm打包模式的sdk

v2.0.0 2021年12月7日

• 变更：修复导出名拼写错误，已更改为RtcVideo
• 变更：合并successCallback、failCallback为resultCallback。并增加了结果码便于统一处理，结果消息变更，详情参考resultCallback说明。
• 变更：statusListener内statusCode变更。
• 增加：autoplayFailCallback参数，用于视频无法自动播放处理。
• 增加：version方法，获取版本号。

v1.1.2 2021年8月3日

• 修复个别旧机型调用destroy方法会抛出异常

v1.1.1 2021年6月25日

• 修复tipListener的参数tipCode不正确

v1.1.0 2021年6月10日

• 增加destroy接口
• failCallback后不会同时触发statusListener的INIT_LOADING_OVER
• 优化网络连接