文档

Web SDK

1. 什么是Web SDK

Wuying Web SDK是用于连接云电脑、云应用的无影Web Client开放接口。通过集成Web Client SDK,客户根据自身业务,快速定制、搭建Web客户端。

2. 快速开始

SDK及demo下载

说明

下载和使用即表示您认可《无影云电脑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