设备助手 Web SDK（H5 / PC）接入-实人认证(ID Verification)-阿里云帮助中心

本文介绍设备助手方案Web SDK（H5 / PC）接入流程。

使用须知

重要

设备助手方案的落地，要求业务方具备成熟的人脸识别算法及风险策略运营体系。建议在接入前与商务经理沟通，以评估业务场景的匹配度。

合规与版本要求

为落实第三方 SDK 集成的隐私合规义务并降低违规风险，请务必使用阿里云文档中心官网发布的最新版本产品。接入前，请仔细阅读个人信息处理规定及《实人认证设备助手SDK隐私政策》。

接入说明

请在需防护的页面中引入 JS SDK。每个网页（含单页应用）仅需引入一次。

兼容性要求

PC 端：Chrome 60+、Firefox 60+、Edge 20+、Safari 11+、360浏览器 10+、QQ浏览器 4+、IE 9+ 等。
移动端：Chrome 60+、UC浏览器 12+、Safari 11+、夸克浏览器、主流手机厂商内置浏览器、原生 WebView（Android 4+）等。

接入步骤

1. 引入JS SDK

Web 端 SDK 以 JS 文件形式提供，并将定期更新。为确保服务正常运行，请勿将该 JS 文件下载至本地服务器进行引入。

<script src="https://o.alicdn.com/captcha-frontend/aliyunFP/fp.min.js"></script>

2. 初始化SDK（init）

在引入 JS SDK 后，建议在页面加载阶段立即执行初始化操作。该操作仅需执行一次，用于获取 SDK 实例对象。

ALIYUN_FP.use('um', (state, um) => {
  if (state === 'loaded') {
    um.init({
        appKey: '【这里填写阿里云分配的AppKey】',
        appName: '【这里填Web应用名称，客户自定义】',
        endpoints : ['https://cloudauth-device.aliyuncs.com']
    })
  }
});

参数说明

appKey：由阿里云分配，用于标识用户身份。请联系商务经理获取。
appName：用户自定义名称。
endpoints：服务域名地址。若未配置，系统将使用默认值https://cloudauth-device.aliyuncs.com。

3. 获取客户端Token（getToken）

通过调用该接口获取设备指纹 deviceToken。建议在触发具体业务行为（如人脸识别）时进行调用。

重要

调用时间间隔：由于数据上报可能存在延迟，请确保 init 接口与 getToken 接口的调用时间间隔大于 2 秒。
绑定业务 ID：调用 getToken 时建议传入 bizId 参数，以将本次 Token 与业务唯一认证 ID 绑定。在服务端查询结果时同步传入该 ID，可用于校验 Token 是否被篡改。

// 1. 直接调用 getToken 接口
window.z_um.getToken();

// 2. 传入本次认证唯一ID
let bizId = '<Your bizId>';
let deviceToken = window.z_um.getToken(bizId);

//3. 推荐方式，传入视频流。
// 此种调用方式 getToken 建议在获取到摄像头权限后再调用。
// 传入本次认证唯一ID和 mediaStream。 mediaStream为视频流对象(用于获摄像头特征)，可直接使用 navigator.mediaDevices.getUserMedia 方法的返回值。
let bizStr = await window.z_um.getCameraInfo(mediaStream);
window.z_um.getToken(bizId, bizStr);

参数说明
- bizId：客户业务 ID，用于关联业务 ID 与 Token。该参数为可选，默认情况下可不传。
- bizStr：摄像头信息（CameraInfo），需通过 getCameraInfo 方法获取，用于提取摄像头特征。
返回值
- deviceToken：返回 Token 字符串，用于后续查询阿里云设备助手接口。

Token 长度说明与异常排查

Token 长度：在网络环境良好的场景下，Token 字符串长度约为 600 字节；在网络环境较差的场景下，Token 长度可能会显著增加。
长 Token 异常排查：若业务中出现大量长 Token，请依次执行以下检查：
1. 检查网络状态：确认客户端网络连接畅通。
2. 调整调用时机：确保 init 接口与 getDeviceToken 接口的调用时间间隔大于 2 秒，或在初始化成功的回调函数中再执行获取 Token 的操作。

4. 携带Token请求服务端

成功获取deviceToken后，可携带此参数请求业务服务器，由服务端查询并校验结果。具体操作，请参见服务端API接口。

完整代码示例

<body>
<button type="button" id='register' onclick="getToken();">获取Token</button>
<script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunFP/fp.min.js"></script>
<script>
ALIYUN_FP.use('um', (state, um) => {
  if (state === 'loaded') {
    um.init({
        appKey: '【这里填写阿里云分配的AppKey】',
        appName: '【这里填Web应用名称，客户自定义】',
        endpoints : ['https://cloudauth-device.aliyuncs.com']
    }
  }
});


//处理业务函数，比如完成认证时
function getToken(){
    var bizId = 'xxxxxxxx';
    //获取设备指纹的deviceToken，getToken和init之间最好相隔2s以上。
    //建议传入本次认证业务唯一ID，生成的token可以和bizId绑定。
    var deviceToken = window.z_um.getToken(bizId);
    //将deviceToken传入客户的服务后台
    var data = {
           "deviceToken": deviceToken,
           "其他业务参数": ""
     };
    //发送后台请求...后台通过deviceToken查询风险信息
}

</script>
</body>