1. 什么是Web SDK
Wuying Web SDK是用于连接云电脑、云应用的无影Web Client开放接口。通过集成Web Client SDK,客户根据自身业务,快速定制、搭建Web客户端。
2. 快速开始
下载和使用即表示您认可《无影云电脑SDK隐私权政策》。
本平台所有文档、SDK、客户端程序仅限于本人或本企业使用,未经阿里云同意不会转发给三方个人或企业。
目录结构
├── WuyingWebDemo.html
├── WuyingWebSDK.js
├── HDXEngine.html
├── HDXLauncher.js
└── sdk
└── ASP
└── container.html
说明: WuyingWebDemo.html -- Sdk例子 WuyingWebSDK.js -- Sdk的接口文件,需要再前端页面中引用该文件 HDXEngine.html -- citrix桌面必要文件,不需要可以移除 HDXLauncher.js -- citrix桌面必要文件,不需要可以移除 sdk -- iframe内嵌资源文件
3. 接口说明
3.1 WebSDK
Name | Type | Description |
apiVersion | string | WebSDK的版本号 |
createSession(sessionId:string, sessionParams: SessionParam)
创建一个云电脑或云应用的session,这里的session与管控的session不是同一个概念
名称 | 类型 | 描述 |
id | string | 创建者自定义,session的唯一标识 |
sessionParams | SessionParam | 创建session参数 |
var userInfo = {
loginToken: loginToken,
sessionId: sessionId,
authCode: authCode,
};
var appInfo = {
appId: appId,
appVersion: appVersion,
loginRegionId: 'cn-shanghai',
};
var sessionParam = {
openType: openType,
iframeId: 'sessionIframe',
resourceType: resourceType,
connectType: 'app',
userInfo: userInfo,
appInfo: appInfo,
};
var wuyingSdk = Wuying.WebSDK;
var session = wuyingSdk.createSession('appstream', sessionParam);
3.2 Methods
start()开始建立连接
var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();
stop()断开连接
var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();
....
session.stop();
addHandle(name: SessionEventType, callback: Function)
增加监听事件
名称 | 类型 | 描述 |
name | string | 监听事件的类型,参考SessionEventType枚举定义 |
callback | Function | 回调函数 |
session.addHandle('getConnectionTicketInfo', (data) => {
console.log(data);
});
session.addHandle('onConnected', (data) => {
console.log('connected', data);
});
session.addHandle('onDisConnected', (data) => {
console.log('disconnect', data);
});
session.addHandle('onRuntimeMsg', (data) => {
document.getElementById('GuestMsgContext').value = JSON.stringify(data);
});
session.start();
sendRuntimeMsg(msg: string, appId: string)
发送消息给Guest内的应用
名称 | 类型 | 描述 |
msg | string | 具体的消息内容 |
appId | string | 消息发送给GuestOS的某个应用 |
var msg = document.getElementById('sendMsgTypeData').value;
var appId = document.getElementById('sendMsgAppId').value;
session.sendRuntimeMsg(msg, appId);
enableInput(param: boolean)
打开和关闭键鼠操作
名称 | 类型 | 描述 |
param | bool | 是否打开 |
enableKeyBoard(param: boolean)
唤起和关闭键盘
名称 | 类型 | 描述 |
param | bool | 是否打开 |
setClipboardEnabled(param: boolean)
剪贴板控制
名称 | 类型 | 描述 |
param | bool | 是否打开 |
setMicrophoneEnabled(param: boolean)
麦克风控制
名称 | 类型 | 描述 |
param | bool | 是否打开 |
setInputEnabled(param: boolean)
输入控制
名称 | 类型 | 描述 |
param | bool | 是否打开 |
setTouchEnabled(param: boolean)
触摸控制
名称 | 类型 | 描述 |
param | bool | 是否打开 |
downloadFile()
打开云电脑内下载文件窗口
uploadFile(file: File)
上传文件
名称 | 类型 | 描述 |
file | File | 上传的文件 |
enableDataIsland(enable: boolean)
显示/隐藏runtime中的数据岛
名称 | 类型 | 描述 |
enable | boolean | 显示/隐藏 |
uploadFileToPds(file: File[])
上传文件到无影网盘
需要先开启文件上传配置,然后通过session.uploadFileToPds
调用
通过onTransferCallback
接收上传进度及报错
名称 | 类型 | 描述 |
file | File | 上传的文件数组 |
downloadFileFromPds(filePath: string)
从无影网盘中下载文件
配置开启文件上传,然后通过session.downloadFileFromPds
调用
名称 | 类型 | 描述 |
filePath | string | 网盘中的文件路径 |
getScreenshot(callback: (blob: Blob) => any, immediate: boolean)
获取当前截图,callback可获取截图的blob,immediate设置为true时直接下载到本地
setResolution(width: number, height: number, degree: number)
设置云电脑/应用画面分辨率,degree为顺时针旋转角度
名称 | 类型 | 描述 |
width | number | 宽度 |
height | number | 高度 |
degree | number | 0或者90 |
stopConnection()
断开连接
getDesktopIdleTime(callback: (time: number) => any)
获取云电脑无操作时间,时间单位ms
setUiParams(param: UiConfig)
session建立后,主动设置UI配置,如菜单是否显示/强制横屏
名称 | 类型 | 描述 |
param | UiConfig | UI选项 |
var uiConfig = {
toolbar: {
visible: false,
},
rotateDegree: 90,
};
session.setUiParams(uiConfig);
3.3 参数类型说明
SessionParam
创建Session的参数
名称 | 类型 | 必填 | 描述 |
openType | OpenType | 是 | iframe内嵌还是新标签页打开 |
iframeId | string | 否 | 如果frame打开,则需要填入iframeId |
sdkPath | string | 否 | 配置sdk文件所在路径,不填默认为相对路径如./ASP/container.html |
resourceType | ResourceType | 是 | 目前只支持打开本地连接页面 |
connectType | ConnectType | 是 | 打开云应用还是云电脑 |
isOverseas | boolean | 否 | 是否海外访问,默认false |
userInfo | UserInfo | 是 | 用户的登录态信息 |
regionId | string | 是 | 打开云电脑时必填为云电脑所在的region |
appInfo | AppInfo | 否 | 打开云应用的信息 |
desktopInfo | DesktopInfo | 否 | 打开云电脑的信息 |
fileInfo | FileInfo | 否 | 网盘相关参数 |
uiConfig | UiConfig | 否 | ui设置项 |
fileTransferConfig | FileTransferConfig | 否 | 文件传输配置 |
logDisabled | bool | 否 | 是否关闭arms统计,默认false不关闭 |
loginType | LoginType | 否 | 默认无影账号登录 |
networkAccessType | 'vpc' | 否 | 默认不填,支持vpc登录 |
UserInfo
用户的登录态信息,现在使用authCode。
名称 | 类型 | 必填 | 描述 |
authCode | string | 是 | 只能用一次的登录态凭证,优先级最高 |
ticket | string | 是 | 1.4.7版本之后支持直接传入ticket建立连接 |
loginToken | string | 是 | 用户登录态信息(deprecated) |
sessionId | string | 是 | 用户登录态信息(deprecated) |
AppInfo
打开云应用的参数
名称 | 类型 | 必填 | 描述 |
appId | string | 是 | 打开的应用id |
appVersion | string | 是 | 打开应用的版本 |
loginRegionId | string | 是 | 云应用资源所在的地域 |
connConfig | ConnConfig | 否 | 连接配置参数 |
appInstanceGroupId | string | 否 | 应用交付组ID |
appInstanceId | string | 否 | 应用实例ID |
taskId | string | 否 | 应用启动任务ID |
bizRegionId | string | 否 | 应用资源所在的地域 |
productType | string | 否 | 交付组类型,默认'CloudApp' |
DesktopInfo
打开云电脑的参数
名称 | 类型 | 必填 | 描述 |
desktopId | string | 是 | 打开的云电脑id |
realDesktopId | string | 否 | 若打开的是云电脑池云电脑则需要传此id |
protocolType | ProtocolType | 否 | 打开云电脑的协议类型 |
loginRegionId | string | 是 | 云电脑资源所在的地域 |
connConfig | ConnConfig | 否 | 连接配置参数 |
assistanceConfig | AssistanceConfig | 否 | 远程协助,不配置默认不开启远程协助 |
creationTime | string | 否 | 云电脑创建时间,UTC格式 |
expiredTime | string | 否 | 云电脑过期时间,UTC格式 |
chargeType | ChargeType | 否 | 云电脑付费类型 |
FileInfo
打开网盘的参数。说明:填入externalDomainId、externalDriveId和externalUserId时支持上传文件至托管pds,此时不需要再填入driveId
名称 | 类型 | 必填 | 描述 |
driveType | string | 是 | 网盘类型(目前只支持设置为"PDS") |
driveId | string | 是 | 网盘ID |
externalDomainId | string | 是 | 用户PDS域ID |
externalDriveId | string | 是 | 用户PDS网盘ID |
externalUserId | string | 是 | 外部用户ID |
fileId | string | 是 | 文件ID |
filePath | string | 否 | 文件路径 |
fileName | string | 否 | 文件名称 |
fileRegion | string | 否 | 文件所在地域,如:cn-hangzhou |
FileTransferConfig
文件上传、下载配置
名称 | 类型 | 必填 | 描述 |
type | string | 否 | 网盘类型(目前只支持设置为"PDS",不填默认为"PDS") |
driveId | string | 否 | 设置上传的网盘ID |
uploadPath | string | 否 | 文件上传路径 |
uploadType | string[] | 否 | 允许上传的文件类型,参考MIME TYPE定义 |
onTransferCallback | function | 否 | 传输信息通知 (type,data=> any |
TransferData
onTransferCallback接收的data内容
名称 | 含义 |
fileName | 上传文件名称 |
fileSize | 上传文件大小 |
fileId | 上传文件id |
progress | 上传文件进度 |
cancelFn | 取消上传回调,上传中调用则取消当前文件上传 |
回调消息代码
type: 'result'
data: {Code, Message?: string, RequestId?: string, fileName?: string, fileSize?: string, fileId?: string}
名称 | 含义 |
ERROR_DRIVE_ID | 网盘id错误 |
ERROR_UPLOAD_PATH | 上传路径错误 |
ERROR_UPLOAD_TYPE | 不允许的文件类型 |
ERROR_FILE_EXISTS | 同名文件已存在 |
ERROR_TOKEN | loginToken失效无法上传 |
ERROR_SERVER | 服务错误,请联系开发 |
ERROR_DOWNLOAD | 下载文件出错 |
SUCCESS_UPLOAD | 上传完成 |
UiConfig
设置连接页面Ui设置
名称 | 类型 | 必填 | 描述 |
toolbar | ToolBarConfig | 否 | 连接页面工具栏显示设置 |
exitCheck | bool | 否 | 退出当前页面浏览器二次确认,默认开启 |
rotateDegree | number | 否 | 强制横屏 (目前只支持0:正常 90:强制横屏) |
vconsoleVisiable | bool | 否 | 是否显示vconsole调试框 |
debugPanelVisiable | bool | 否 | 是否显示码流、帧率等信息框 |
reconnectType | ReconnectType | 否 | 重连提示框样式 |
defaultResolution | ResolutionType | 否 | 首次连接的默认分辨率,默认为'A' |
language | Language | 否 | 设置内部弹窗提示的语言,默认为中文 |
ToolBarConfig
工具栏显示设置
名称 | 类型 | 必填 | 描述 |
visible | bool | 否 | 工具栏是否显示 |
noMenu | bool | 否 | 悬浮球式否支持打开右键菜单,默认false,1.4.20以上支持 |
ConnConfig
连接配置参数
名称 | 类型 | 必填 | 描述 |
decodeType | ConnDecodeType(数字枚举) | 否 | 编码方式配置 |
playSoundBackground | bool | 否 | 切换后台后是否继续播放声音 |
AssistanceConfig
连接配置参数注意作为管理员连接时,远程协助的连接是一次性的,但是ticket目前是可以多次使用的,连接一次后应当清除ticket防止重连
名称 | 类型 | 必填 | 描述 |
role | AssistanceRole | 是 | 当前使用远程协助的角色 |
aliUid | string | 否 | 租户id,用于用户发起远程协助请求,role为user时必填 |
ticket | string | 否 | 管理员协助参数,调用GetCoordinateTicket接口获取, role为admin时必填 |
taskId | string | 否 | 管理员协助参数,调用GetCoordinateTicket接口获取, role为admin时必填 |
coId | string | 否 | 管理员协助参数,调用GetCoordinateTicket接口获取, role为admin时必填 |
remoteAssistance | string | 否 | 管理员协助参数,默认传'on', role为admin时必填 |
accessKeyId | string | 否 | 管理员协助参数,role为admin时必填,用于键鼠控制 |
accessKeySecret | string | 否 | 管理员协助参数,role为admin时必填,用于键鼠控制 |
枚举类型
OpenType
打开云电脑或者云应用的方式枚举
名称 | 含义 |
newTab | 新的tab页面打开 |
inline | 内嵌Iframe页面打开 |
urlScheme | 支持本地原生客户端打开,需安装6.2以上版本无影桌面端 |
ConnectType
打开云电脑或者云应用枚举
名称 | 含义 |
app | 打开云应用 |
desktop | 打开云电脑 |
ResourceType
打开本地连接页面还是无影WebClient
名称 | 含义 |
local | 打开本地连接HTML页面 |
ReconnectType
重连提示弹窗的ui
名称 | 含义 |
simple | 简单的loading |
normal | 倒计时弹窗 |
ResolutionType
初始化连接默认分辨率(连接时优先取用户设置过的分辨率)
名称 | 含义 |
A | 速度优先,当前窗口大小 |
B | 质量优先,当前窗口大小乘以window.devicePixelRatio |
ChargeType
云电脑付费类型
名称 | 含义 | 开始支持版本 |
PostPaid | 按量付费 | 1.4.0 |
PrePaid | 包年包月付费 | 1.4.0 |
Language
语言设置选项,默认为zh-CN
名称 | 含义 |
zh-CN | 中文 |
en-US | 英文 |
ja-JP | 日文 |
LoginType
登录云电脑方式
名称 | 含义 |
aliyunLogin | 阿里云账号登录 |
normalLogin | 无影账号登录 |
事件说明
SessionEventType
session的事件类型映射
名称 | 含义 | 开始支持版本 |
getConnectionTicketInfo | 连接云电脑、云应用事件 | 1.0.0 |
onConnected | 云应用、云电脑建立连接事件 | 1.0.0 |
onDisConnected | 云应用、云电脑断开连接事件 | 1.0.0 |
onRuntimeMsg | Runtime内发送给SDK的消息 | 1.1.0 |
networkData | 网络性能参数 | 1.3.1 |
onError | 接受连接过程中的错误 | 1.4.1 |
Guest消息类型
GuestMsgType
发送给GuestOS消息的类型
名称 | 含义 | 开始支持版本 |
RUNTIME_API_MESSAGE | 发送给GuestOS消息 | 1.1.0 |
流的解码类型
ConnDecodeType
名称 | 含义 | 开始支持版本 |
0 | 软解 | 1.2.0 |
1 | 硬解 | 1.2.0 |
2 | webrtc | 1.2.0 |
云电脑相关
ProtocolType
名称 | 含义 | 开始支持版本 |
ASP | asp协议云电脑 | 1.3.0 |
HDX | citrix协议云电脑 | 1.3.0 |
远程协助类型
AssistanceRole
名称 | 含义 | 开始支持版本 |
user | 用户 | 1.3.0 |
admin | 管理员 | 1.3.0 |
shared_user | 共享云电脑用户 | 1.3.1 |
assistant | 接受共享协同用户 | 1.4.0 |
3.4 错误代码说明
onDisconnected接收断连的报错信息
名称 | 含义 | 代码 |
ASP_CLIENT_DISCONNECT_CONNECT_ERROR | 断开连接 | 0 |
ASP_CLIENT_DISCONNECT_SOCKET_CLOSE | socket关闭 | 1 |
ASP_CLIENT_DISCONNECT_WEBRTC_CLOSE | webrtc关闭 | 2 |
ASP_CLIENT_DISCONNECT_CLOUD_APP_STOP | 云应用关闭 | 2001 |
ASP_CLIENT_DISCONNECT_CLIENT_PREEMPTION | 被抢占 | 2002 |
ASP_CLIENT_DISCONNECT_GUEST_SHUTDOWN_REBOOT | Guest重启 | 2003 |
ASP_CLIENT_RTT_TIMEOUT | RTT超时 | 2200 |
ASP_CLIENT_NET_ERROR_IO | 网络IO错误 | 2201 |
ASP_CLIENT_UPDATE_TICKET_FAILED | 更新ticket错误 | 2202 |
onError接收连接过程的错误信息
接受格式{code: string, message: string, api: string}
错误code列举如下,message包含requestId,api为报错的请求
错误code |
InvalidClientType.AccessDenied |
DesktopCpuHighLoad |
NotFindDesktopId |
UnavailableDesktop.NotRegistered |
NotFoundUserDesktop |
PRICE.WAN_HUA_TONG_SYS |
UnavailableDesktop |
AUTHORIZE_FAILED |
UnavailableDesktop.Initializing |
NotFindTaskId |
GENERAL_ERROR |
InvalidVersion |
UnavailableDesktop.Unregistered |
Forbidden |
InvalidDesktopId.NotFound |
PRICE.RATING_ACCOUNT_SYS |
AgentUnbinding |
USING_DESKTOP |
NoMoreActiveSessions |
GET_TICKET_LOCK |
DistributeLockFailed |
MissingLoginToken |
DesktopsUnderMaintenance |
NoEnoughDesktops |
InvalidTimeStamp.Expired |
GeneralAppLaunchError |
InvalidClientIp.Policy |
MissingClientId |
ACCOUNT.ALIYUN_ACCOUNT_NOT_EXIST |
DesktopNotReady |
InvalidAccessKeyId.NotFound |
CouldNotConnectToWorkstation |
AssignUserFailed |
InvalidTimeStamp.Format |
INVALID_CSRF_TOKEN |
INTERNAL_ERROR |
DesktopUnavailable |
UnavailableDesktop.ConnectionBroken |
AuthorizeFailed.OfficeSIteId |
SignatureDoesNotMatch |
USER_NOT_EXIST |
MissingAccessKeyId |
ServiceUnavailable |
NOT_LOGIN |
UnavailableDesktop.ServerNotReady |
InvalidDesktopId.Status |
PermissionDeny.Desktop |
InvalidOperation.NotSupportedEndpoint |
InvalidAccessKeyId |