云手机Web SDK
云手机Web SDK 主要功能是为Web赋予直连云手机的能力,用户在运营平台配置好云手机之后,Web端通过SDK进行直连操作。
Web SDK 发行版包
云手机Web SDK 发行版包括云手机Web SDK文档、JSSDK 文档、完整的Demo示例。以下使用
<SDK_PATH>
表示SDK解压根目录。
- 对接文档:
<SDK_PATH>/sdk/云手机Web SDK文档.md
,原文档- JSSDK 文档:
<SDK_PATH>/sdk/JSSDK 文档.docx
,JSSDK文档- 示例项目源码:
<SDK_PATH>/sdk/index.html
,Demo文件- Web SDK:
<SDK_PATH>/sdk/
websdk/*,Web SDK文件,封装了请求sdk接口的相关方法- JSSDK:
<SDK_PATH>/sdk/
jssdk/*,JSSDK文件,JSSDK封装对直连实例进行操作的相关方法和回调
云手机 Web SDK 使用
版本号 | 更新时间 | 下载地址 | 备注 |
---|---|---|---|
latest | - | Web SDK下载 | 最新版本 |
V 1.0.5 | 2021.12.27 | Web SDK下载 | 性能优化,提升稳定性 |
V 1.0.4 | 2021.08.30 | Web SDK下载 | JSSDK支持按需开启语音权限、摄像头上下旋转 |
V 1.0.3 | 2021.07.09 | Web SDK下载 | JSSDK支持支持开启扫码和人脸识别功能、更新Demo |
V 1.0.2 | 2021.07.02 | Web SDK下载 | 新增透传云端方法 |
V 1.0.1 | 2021.06.28 | Web SDK下载 | 更新优化index.html文件 |
V 1.0.0 | 2021.06.11 | Web SDK下载 | 包含Web SDK对接相关文件 |
运行环境
需要服务器运行环境,添加域名白名单,支持现代浏览器PC、H5端。
SDK引入及配置
申请密钥对(AK和SK)
登录百度智能云控制台,进入“云手机>安全组> 秘钥对”页面
ID | AK | SK | 类型 |
---|---|---|---|
n | u7fkUQ3mjGaqZAHr08****** | HiIkc0fp8rGVKo3T7a2QeEtDmR5vX4jUWO****** | SDK |
引入SDK
WebSDK 依赖 JSSDK,需要按顺序引入。latest代表最新版,也可以替换为具体版本,如redfinger.min.210602.js。
<!--JSSDK-->
<script src="//bj.bcebos.com/v1/yunapp-static/bac/sdk/jssdk/redfinger.min.latest.js"></script>
<!--Web SDK-->
<script src="//bj.bcebos.com/v1/yunapp-static/bac/sdk/websdk/yap-utils.umd.latest.js"></script>
SDK权限配置
需要提供开发者域名并联系相关人员添加域名白名单,未添加白名单访问会出现跨域问题。
快速入门
HTML:
<button onclick="play()">直连</button>
<!--实例标签-->
<div id="play-box" style="height: 500px"></div>
<!--JSSDK-->
<script src="//bj.bcebos.com/v1/yunapp-static/bac/sdk/jssdk/redfinger.min.latest.js"></script>
<!--Web SDK-->
<script src="//bj.bcebos.com/v1/yunapp-static/bac/sdk/websdk/yap-utils.umd.latest.js"></script>
JavaScript:
// 替换百度智能云-云手机 AK、SK
const ak = 'PVr5RaC0p58Bo***';
const sk = 'VBy9VWdaUP1q4W8xLXrr2MEZqMDKe***';
/*
* 获取实例编号地址 https://console.bce.baidu.com/bac#/example/list 实例编号
* 设备编码:非必填,padCode与appId不能同时为空,同时存在padCode优先,存在padCode则直连云手机
* 获取设备编码地址 https://console.bce.baidu.com/bac#/app/list 应用ID
* 应用id:非必填,应用id不为空表示应用直连,否则为云手机直连。直连应用还需要填写pkgName用来使SDK启动云手机应用,appId通知服务端直连应用。
* userId:必填,内容自定义
* */
const padCode = 'VM010151089016';
const appId = '100705';
const userId = 'baidu';
const pkgName = 'com.xxx.xxx';
const Sign = yapUtils.Sign; // 签名方法
const Tools = yapUtils.tools; // 接口封装
const axios = yapUtils.axios; // 封装axios
function play() {
// 申请直连实例接口签名
let sign = new Sign({
ak: ak,
sk: sk,
host: 'https://yunapp-api.baidu.com/api/armcmapi',
path: '/sdk/v1/device/connect/apply',
params: {
padCode: padCode,
appId: appId,
userId: userId,
}
});
// 申请直连实例
axios({
method: 'post',
url: sign.getUrl(), // 获取签名后的请求地址
data: sign.getBody(), // 获取签名后的请求体
headers: {
appKey: ak
}
}).then(res => {
// 获取直连设备信息
if (res.data.data && res.data.data.connectInfo) {
const deviceToken = JSON.stringify(res.data.data.connectInfo.deviceToken);
// 发起直连,Tools.play 封装了 redfinger.play,参考JSSDK 文档1.直连实例
Tools.play({
app: {pkgName: pkgName}, // 直连应用包名
deviceToken
}, redfinger, {})
}
});
}
JSSDK
JSSDK 封装对直连实例进行操作的相关方法和回调,JSSDK 的核心对象为 window.redfinger。
redfinger 属性
redfinger.config // 返回实例配置信息
redfinger.version // 返回JSSDK版本
redfinger 方法
redfinger.sendCommand(redfinger.KEY_TYPE. KEY_HOMEPAGE) // 指令控制方法 - 返回桌面
redfinger.destory(); // 退出直连
redfinger 回调
redfinger.onRunInformation = function(type, info) { // 运行信息回调
console.log(type, info)
}
redfinger H5&云端消息透传相关方法回调
// 云端透传失败回调
redfinger.onTransparentMsgFailed = function (type, msg, service) {
console.log('onTransparentMsgFailed', type, msg, service)
}
// 云端透传回调
redfinger.onTransparentMsg = function (type, msg, service) {
console.log('onTransparentMsg', type, msg, service)
}
// 透传云端消息
redfinger.sendTransparentMsg(type, otpions, packageName);
// type 类型H5端默认为 1
// packageName ${应用包名}/com.baidu.operationsdk.BDGameService
// otpions 透传信息,数据格式需要转化为json格式
var options = {
'pkg': 'com.yunserver.serverapp', // 应用包名
'action': 'CUSTOM_DATA', // 透传动作
'extraData': {'uid': '设备号:VM010151094070 时间戳:1625140088930'} // 透传自定义信息
};
// options 数据格式转换JSON
options = JSON.stringify(options);
// 发送示例:
redfinger.sendTransparentMsg(1, options, 'com.yunserver.serverapp/com.baidu.operationsdk.BDGameService');
// 实际发送数据格式:
redfinger.sendTransparentMsg(1,'{\\"pkg\\":\\"com.yunserver.serverapp\\",\\"action\\":\\"CUSTOM_DATA\\",\\"extraData\\":{\\"uid\\":\\"设备号:VM010151094070 时间戳:1625140088930\\"}}', 'com.yunserver.serverapp/com.baidu.operationsdk.BDGameService');
redfinger 支持扫码和人脸识别功能
redfinger.config.isCameraLive = true // 开启扫码功能
redfinger 开启语音功能
redfinger.config.isMicrophoneLive = true; // 开启语音权限
redfinger 摄像头上下反转
// 解决部分云手机设备摄像头上下倒置问题
redfinger.config.cameraTransform = 180; // 值为摄像头上下旋转角度,可选项 0、180
更多API请参考:JSSDK 文档
Web SDK
Web SDK 封装了Web端请求SDK接口的相关方法,Web SDK的核心对象为 window.yapUtils。
yapUtils.Sign
yapUtils封装了请求SDK接口的签名方法。
// 实例化Sign给SDK申请直连实例接口签名
const sign = new Sign({
ak: ak,
sk: sk,
host: 'https://yunapp-api.baidu.com/api/armcmapi',
path: '/sdk/v1/device/connect/apply',
params: {
padCode: padCode,
appId: appId,
userId: userId,
onlineTime: 60 * 10
}
});
yapUtils.axios
yapUtils对axios进行了封装。
// 使用签名后的地址和请求提发起 axios 请求
axios({
method: 'post',
url: sign.getUrl(), // 获得签名后请求地址
data: sign.getBody(), // 获得签名后的请求体
headers: {
appKey: ak
}
}).then(res => {
console.log('申请直连实例返回:', res);
});
yapUtils.tools
yapUtils.tools 封装了redfinger的部分方法和回调。
1. Tools.play() 接口参数说明
参数:类型 | 必填 | 默认值 | 释义 |
---|---|---|---|
response: PlayResponse |
是 | - | Tools.getDevice()接口返回的数据,PlayResponse 格式见下表1.1 |
redfinger: any |
是 | - | 百度红手指提供的全局对象 redfinger |
opt: InitConfig |
是 | - | 参数配置,回调接口,InitConfig 格式见下表1.2 |
1.1 response: PlayResponse 数据结构说明
参数:类型 | 必填 | 默认值 | 释义 | 备注 |
---|---|---|---|---|
app: object |
是 | {pkgName:"" } |
包名 | 包名传空,会直接拉起云手机传包名,会拉起对应app |
` deviceToken: string` | 是 | - | token | 这个token,是百度智能云手机开放接口返回的一个字符串 |
1.2 opt: InitConfig 格式说明
参数:类型 | 必填 | 默认值 | 释义 | 备注 |
---|---|---|---|---|
isWebRTC: boolean |
否 | falses | 是否开启webRTC | |
divName: string |
否 | 'play-box' | 投屏区域,div 的id | |
onError: Function |
否 | noop | 报错的回调 | |
isWss: boolean |
否 | false | 是否使用wss | |
keyboard:boolean | 否 | false | 是否开启键盘输入 | |
onTimeout: Function |
否 | noop | 设备闲置到了设定的时间的回调 | |
onStartPlay: Function |
否 | noop | 开始直连前的回调 | |
onWebrtcRunInfo: Function |
否 | noop | webRtc 投屏信息的回调 | |
onOpen: Function | 否 | noop | 出现画面的回调 | |
timeout: number |
否 | 3 | 无操作时间 ,单位分,前台闲置超时时长后台闲置超时时间需要联系接口人更改相应控制服务 | |
adapt:Adapt |
否 | - | 直连云手机的画质信息,格式见下表2.2.1 |
1.2.1 adapt:Adapt 格式说明 注意:如果运营平台适配的应用的参数,将会采用运营平台的设置
参数:类型 | 必填 | 默认值 | 释义 | 备注 |
---|---|---|---|---|
compressionType: number |
否 | 3 | 压码方式3: 硬压4: 软压 | |
sound: number |
否 | 1 | 1: 开启声音!1: 关闭声音 | |
fps: number |
否 | 20 | 帧率 | |
bitrate: number |
否 | 3200 | 码率 | |
resolution: number | 否 | 3 | 分辨率1: 低;2: 标清 480p;3: 高清 720p;4: 超清 1080p | 非webRTC 的情况下,超清是720p, 建议手动设置为4 |
附录 Web SDK & JSSDK
SDK版本记录
JSSDK:
- redfinger.min.210602.js:支持百度智能云云手机直连播放
- redfinger.min.210701.js:新增H5&云端消息透传相关方法回调
- redfinger.min.210709.js:支持开启扫码和人脸识别功能
- redfinger.min.210726.js:JSSDK 默认支持语音功能
- redfinger.min.210804.js:JSSDK 优化
- redfinger.min.210810.js:修复bug
- redfinger.min.210825.js:支持摄像头上下反转
- redfinger.min.210826.js:按需开启语音权限
- redfinger.min.1.5.6.js:优化性能,提升稳定性
- redfinger.min.latest.js:redfinger.min.1.5.6.js
Web SDK:
- yap-utils.umd.210611.js:支持百度智能云云手机直连播放
- yap-utils.umd.latest.js:yap-utils.umd.210611.js
DEMO示例
测试地址:https://bj.bcebos.com/v1/yunapp-static/bac/sdk/index.html
DEMO源码:bac/sdk/index.html
二维码:
Q & A
- 部署DEMO需要替换AK、SK、padCode等。运行DEMO需要服务器运行环境,如部署服务器需要添加域名白名单才能访问,否则会出现跨域问题:Access to XMLHttpRequest at 'https://yunapp-api.baidu.com/api/armcmapi/sdk/v1/device/connect/apply?padCode=VM010151089016&appId=100705&onlineTime=600&auth_ver=2&appkey=PVr5RaC0p58BoXQ2&time=1623728218793&sign=a90d3aa4f2db4bfa5910529526f0ea20' from origin 'http://localhost:63342' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.。
- 直连提示message: 没有可直连该应用的实例,status: 5800003。设备被占用,需要释放上一次直连设备,或者直连其他设备。
- 释放设备周期,经历哪些阶段,需要多久?
设备释放是异步的,根据实例配置,释放直连设备后可能需要经过清理缓存、重启设备、初始化等,时间无法准确评估。
- 直连云手机模式。
直连云手机分为两种模式,js模式和Webrtc模式,两种模式都基于WebSocket。
js模式会在浏览器中插入canvas进行渲染,Webrtc模式会在浏览器中插入video进行播放云手机画面,性能更优。
直连时使用Webrtc模式需要修改isWebRTC和升级设备支持Webrtc,火狐浏览器暂不支持Webrtc模式。
Tools.play({ app: {pkgName: ''}, deviceToken: deviceToken }, redfinger, { isWebRTC: true, // 是否开启Webrtc。(开启Webrtc以后性能会有所提升,需要升级设备支持Webrtc) isWss: true, // 是否支持https })
- 是否支持https?
直连云手机支持https,直连时isWss设置为true即可,默认为false。如果isWss为false时,通过https访问则会报错:Mixed Content: The page at 'blob:https://bj.bcebos.com/448d8622-b8ab-456d-b426-c5e4ba1b7256' was loaded over HTTPS, but attempted to connect to the insecure WebSocket endpoint 'ws://gznx.cloud-control.top:9701/'. This request has been blocked; this endpoint must be available over WSS.
- 如何调用云手机home键?
参考JSSDK 文档第12.指令控制方法 使用场景:当用户按下返回、home键、任务键(Menu)时 使用方法: redfinger.sendCommand(command) 参数说明:包含返回、Home、和Menu redfinger.KEY_TYPE = { KEY_MENU : 139, KEY_BACK : 158, KEY_HOMEPAGE : 172 } 返回桌面:举例 redfinger.sendCommand(redfinger.KEY_TYPE.KEY_HOMEPAGE) 调试技巧: 直连云手机后,直接在浏览器控制台输入此方法即可执行。