Wuying Web SDK integration-Elastic Desktop Service-阿里云帮助中心

The Web SDK connects the Alibaba Cloud Workspace Web client to Elastic Desktop Service (EDS) instances and App Streaming. Integrate the SDK to build a web client that matches your own business requirements.

Quick start

Prerequisites

Before you create a session, make sure that the following items are in place:

SDK files — Reference WuyingWebSDK.js in your front-end page. Keep HDXEngine.html and HDXLauncher.js in the deployment package if you connect to Citrix desktops.
Logon credential — Obtain a credential for SessionParam.userInfo. authCode takes the highest priority.
Resource information — Set SessionParam.connectType to app or desktop, and provide the matching resource information in SessionParam.appInfo or SessionParam.desktopInfo. SessionParam.regionId is required when you connect to an EDS instance.
Session container — Provide SessionParam.iframeId if you open the session in an embedded iframe.
SDK path — Set SessionParam.sdkPath if the SDK resource files are not at the default relative path, such as ./ASP/container.html.

Download the SDK and demo

Download the SDK package and the demo from SDK and demo downloads.

By downloading and using the SDK, you agree to the Elastic Desktop Service SDK Privacy Policy.

The documentation, SDKs, and client programs on this platform are for your personal or enterprise use only and may not be distributed to any third party without the consent of Alibaba Cloud.

Directory structure

├── WuyingWebDemo.html
├── WuyingWebSDK.js
├── HDXEngine.html
├── HDXLauncher.js
└── sdk
     └── ASP
          └── container.html

The package contains the following files:

WuyingWebDemo.html — An SDK example.
WuyingWebSDK.js — The SDK interface file. Reference this file in your front-end page.
HDXEngine.html — Required for Citrix desktops. Remove it if you do not use Citrix desktops.
HDXLauncher.js — Required for Citrix desktops. Remove it if you do not use Citrix desktops.
sdk — A directory that contains the resource files for the iframe.

Integration flow

Reference WuyingWebSDK.js in your front-end page.
Get the SDK object from Wuying.WebSDK and call createSession to create a session.
Call addHandle to register the event listeners that you need.
Call start to establish the connection.

API reference

The SDK exposes two layers of interfaces: Wuying.WebSDK is the global object that creates sessions, and the session instance that createSession returns carries the runtime methods for connection control, messaging, peripheral control, and file transfer. For the session methods, see Session methods.

Wuying.WebSDK object

The following table describes the property of the Wuying.WebSDK object.

Property	Type	Description
apiVersion	string	The version number of the Web SDK.

createSession(sessionId: string, sessionParams: SessionParam)

Creates a connection session for an EDS instance or a cloud application. A connection session is not the same concept as a management session.

Parameter	Type	Description
sessionId	string	A unique identifier for the session. Defined by the caller.
sessionParams	SessionParam	The parameters used to create the 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);

Session methods

The following methods apply to the session object that createSession() returns.

Method	Group	Purpose
start()	Connection control	Starts a connection.
stop()	Connection control	Disconnects.
stopConnection()	Connection control	Disconnects the current session.
addHandle()	Messaging	Adds an event listener.
sendRuntimeMsg()	Messaging	Sends a message to an application in the guest OS.
enableInput()	Input and peripheral control	Enables or disables keyboard and mouse input.
enableKeyBoard()	Input and peripheral control	Shows or hides the keyboard.
setClipboardEnabled()	Input and peripheral control	Enables or disables the clipboard.
setMicrophoneEnabled()	Input and peripheral control	Enables or disables the microphone.
setInputEnabled()	Input and peripheral control	Enables or disables input.
setTouchEnabled()	Input and peripheral control	Enables or disables touch input.
downloadFile()	File transfer	Opens the file download window inside the EDS instance.
uploadFile()	File transfer	Uploads a file.
uploadFileToPds()	File transfer	Uploads files to PDS.
downloadFileFromPds()	File transfer	Downloads a file from PDS.
setResolution()	Display and UI	Sets the display resolution of the EDS instance or cloud application.
setUiParams()	Display and UI	Sets UI options after the session is established.
enableDataIsland()	Display and UI	Shows or hides the data island in the runtime.
getScreenshot()	Display and UI	Takes a screenshot of the current screen.
getDesktopIdleTime()	Status query	Queries the idle time of the EDS instance.

Connection control

start()

Starts a connection.

var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();

stop()

Disconnects.

var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();
// Your business logic here
session.stop();

stopConnection()

Disconnects the current session.

Messaging

addHandle(name: SessionEventType, callback: Function)

Adds an event listener.

Parameter	Type	Description
name	SessionEventType	The type of event to listen for. See SessionEventType.
callback	Function	The callback function that runs when the event occurs.

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)

Sends a message to an application in the guest OS.

Parameter	Type	Description
msg	string	The message content.
appId	string	The ID of the target application in the guest OS.

var msg = document.getElementById('sendMsgTypeData').value;
var appId = document.getElementById('sendMsgAppId').value;
session.sendRuntimeMsg(msg, appId);

Input and peripheral control

enableInput(param: boolean)

Enables or disables keyboard and mouse input.

Parameter	Type	Description
param	boolean	Whether to enable keyboard and mouse input.

enableKeyBoard(param: boolean)

Shows or hides the keyboard.

Parameter	Type	Description
param	boolean	Whether to show the keyboard.

setClipboardEnabled(param: boolean)

Enables or disables the clipboard.

Parameter	Type	Description
param	boolean	Whether to enable the clipboard.

setMicrophoneEnabled(param: boolean)

Enables or disables the microphone.

Parameter	Type	Description
param	boolean	Whether to enable the microphone.

setInputEnabled(param: boolean)

Enables or disables input.

Parameter	Type	Description
param	boolean	Whether to enable input.

setTouchEnabled(param: boolean)

Enables or disables touch input.

Parameter	Type	Description
param	boolean	Whether to enable touch input.

File transfer

Before you call uploadFileToPds or downloadFileFromPds, enable file transfer in SessionParam.fileTransferConfig. Set onTransferCallback in the same structure to receive transfer notifications: the callback payload is described in TransferData, and the result codes are listed in File transfer callback codes.

downloadFile()

Opens the file download window inside the EDS instance.

uploadFile(file: File)

Uploads a file.

Parameter	Type	Description
file	File	The file to upload.

uploadFileToPds(file: File[])

Uploads files to Drive and Photo Service (PDS). Enable file transfer in SessionParam.fileTransferConfig, and then call session.uploadFileToPds. Use onTransferCallback to track upload progress and errors.

Parameter	Type	Description
file	File[]	The files to upload.

downloadFileFromPds(filePath: string)

Downloads a file from PDS. Enable file transfer in SessionParam.fileTransferConfig, and then call session.downloadFileFromPds.

Parameter	Type	Description
filePath	string	The path of the file in PDS.

Display and UI

setResolution(width: number, height: number, degree: number)

Sets the display resolution of the EDS instance or cloud application.

Parameter	Type	Description
width	number	The width.
height	number	The height.
degree	number	The clockwise rotation angle, in degrees. Valid values: `0` and `90`.

setUiParams(param: UiConfig)

Sets UI options after the session is established, such as whether to show the menu or force landscape orientation.

Parameter	Type	Description
param	UiConfig	The UI options.

var uiConfig = {
  toolbar: {
    visible: false,
  },
  rotateDegree: 90,
};
session.setUiParams(uiConfig);

enableDataIsland(enable: boolean)

Shows or hides the data island in the runtime.

Parameter	Type	Description
enable	boolean	Whether to show the data island.

getScreenshot(callback: (blob: Blob) => any, immediate: boolean)

Takes a screenshot of the current screen.

Parameter	Type	Description
callback	(blob: Blob) => any	The callback that receives the screenshot as a `Blob`.
immediate	boolean	Whether to download the screenshot directly to the local machine.

Status query

getDesktopIdleTime(callback: (time: number) => any)

Queries the idle time of the EDS instance.

Parameter	Type	Description
callback	(time: number) => any	The callback that receives the idle time, in milliseconds.

Parameter types

The following sections describe the object types that the Web SDK accepts. In the Required column, Conditional indicates that the parameter is required only in the scenario stated in its description.

SessionParam

Parameters for creating a session.

Parameter	Type	Required	Description
openType	OpenType	Yes	Whether to open the session in an embedded iframe or a new tab.
iframeId	string	Conditional	The ID of the iframe. Required if you open the session in an iframe.
sdkPath	string	No	The path of the SDK file. Default value: a relative path such as `./ASP/container.html`.
resourceType	ResourceType	Yes	The resource type. Only `local` is supported, which opens the local connection page. See ResourceType.
connectType	ConnectType	Yes	Whether to connect to a cloud application or an EDS instance.
isOverseas	boolean	No	Whether the access request originates outside the Chinese mainland. Default value: `false`.
userInfo	UserInfo	Yes	The logon credential of the user.
regionId	string	Conditional	The region of the EDS instance. Required if you connect to an EDS instance.
appInfo	AppInfo	No	Information about the cloud application to open.
desktopInfo	DesktopInfo	No	Information about the EDS instance to open.
fileInfo	FileInfo	No	The PDS settings.
uiConfig	UiConfig	No	The UI settings.
fileTransferConfig	FileTransferConfig	No	The file transfer settings.
logDisabled	boolean	No	Whether to disable Application Real-Time Monitoring Service (ARMS) monitoring. Default value: `false`, which keeps monitoring enabled.
loginType	LoginType	No	The logon type. Default value: an Elastic Desktop Service account.
networkAccessType	'vpc'	No	The network access type. Optional. Set the value to `'vpc'` to sign in over a VPC.

UserInfo

The logon credential of the user. Provide one credential: authCode takes the highest priority, and loginToken and sessionId are deprecated.

Parameter	Type	Required	Description
authCode	string	Conditional	A one-time logon credential that is valid for 10 minutes. Takes the highest priority. Call `GetConnectionTicket` to obtain a new `authCode` each time a user initiates a connection to the Elastic Desktop Service, and do not cache the credential. Use `addHandle("onError", callback)` to register a callback function for connection errors: a `MissingLoginToken` or `InvalidTimeStamp.Expired` error code indicates that the `authCode` is no longer valid, so obtain a new credential and connect again.
ticket	string	Conditional	A ticket that establishes a connection directly. Supported in 1.4.7 and later.
loginToken	string	Conditional	Deprecated. Logon session information of the user.
sessionId	string	Conditional	Deprecated. Logon session information of the user.

AppInfo

Parameters for launching a cloud application.

Parameter	Type	Required	Description
appId	string	Yes	The ID of the application to open.
appVersion	string	Yes	The version of the application to open.
loginRegionId	string	Yes	The region of the cloud application resource.
connConfig	ConnConfig	No	The connection settings.
appInstanceGroupId	string	No	The ID of the application delivery group.
appInstanceId	string	No	The ID of the application instance.
taskId	string	No	The ID of the application startup task.
bizRegionId	string	No	The region of the application resource.
productType	string	No	The type of the delivery group. Default value: `CloudApp`.

DesktopInfo

Parameters for launching an EDS instance.

Parameter	Type	Required	Description
desktopId	string	Yes	The ID of the EDS instance to open.
realDesktopId	string	Conditional	The ID of the actual EDS instance. Required if you open an EDS instance from an instance pool.
protocolType	ProtocolType	No	The protocol used to connect to the EDS instance.
loginRegionId	string	Yes	The region of the EDS instance resource.
connConfig	ConnConfig	No	The connection settings.
assistanceConfig	AssistanceConfig	No	The remote assistance settings. Remote assistance is disabled if this parameter is not set.
creationTime	string	No	The time when the EDS instance was created, in UTC.
expiredTime	string	No	The time when the EDS instance expires, in UTC.
chargeType	ChargeType	No	The billing method of the EDS instance.

FileInfo

Parameters for accessing PDS. Specify externalDomainId, externalDriveId, and externalUserId to upload files to a managed PDS without specifying driveId.

Parameter	Type	Required	Description
driveType	string	Yes	The drive type. Only `PDS` is supported.
driveId	string	Conditional	The drive ID. Required if you do not specify `externalDomainId`, `externalDriveId`, and `externalUserId`.
externalDomainId	string	Conditional	The PDS domain ID of the user. Required if you upload files to a managed PDS instead of specifying `driveId`.
externalDriveId	string	Conditional	The PDS drive ID of the user. Required if you upload files to a managed PDS instead of specifying `driveId`.
externalUserId	string	Conditional	The external user ID. Required if you upload files to a managed PDS instead of specifying `driveId`.
fileId	string	Yes	The file ID.
filePath	string	No	The file path.
fileName	string	No	The file name.
fileRegion	string	No	The region where the file is stored. Example: `cn-hangzhou`.

FileTransferConfig

File upload and download settings.

Parameter	Type	Required	Description
type	string	No	The drive type. Only `PDS` is supported. Default value: `'PDS'`.
driveId	string	No	The ID of the drive to upload files to.
uploadPath	string	No	The path to upload files to.
uploadType	string[]	No	The file types allowed for upload, as MIME types.
onTransferCallback	Function	No	The callback that receives transfer notifications. Signature: (type, data) => any. For result codes, see File transfer callback codes.

TransferData

The data that onTransferCallback receives.

Field	Description
fileName	The name of the file.
fileSize	The size of the file.
fileId	The ID of the file.
progress	The upload progress.
cancelFn	The callback that cancels the upload. Calling it during an upload cancels the current file transfer.

UiConfig

UI settings for the connection page.

Parameter	Type	Required	Description
toolbar	ToolBarConfig	No	The toolbar settings for the connection page.
exitCheck	boolean	No	Whether the browser asks for confirmation before you exit the current page. Enabled by default.
rotateDegree	number	No	Whether to force landscape orientation. Valid values: `0` (normal) and `90` (landscape).
vconsoleVisiable	boolean	No	Whether to show the VConsole debugging box.
debugPanelVisiable	boolean	No	Whether to show the information box that reports details such as bitrate and frame rate.
reconnectType	ReconnectType	No	The style of the reconnection dialog.
defaultResolution	ResolutionType	No	The resolution used for the initial connection. Default value: `'A'`.
language	Language	No	The language of the internal pop-up prompts. Defaults to Chinese.

ToolBarConfig

Toolbar display settings.

Parameter	Type	Required	Description
visible	boolean	No	Whether to show the toolbar.
noMenu	boolean	No	Whether the toolbar supports opening the right-click menu. Default value: `false`. Supported in Web SDK 1.4.20 and later.

ConnConfig

Connection settings.

Parameter	Type	Required	Description
decodeType	ConnDecodeType	No	The encoding type. A numeric enumeration.
playSoundBackground	boolean	No	Whether sound keeps playing after the application enters the background.

AssistanceConfig

Remote assistance settings.

Important

A remote assistance connection made by an administrator is single-use, but the ticket can be reused. Clear the ticket after the initial connection to prevent reconnection.

Parameter	Type	Required	Description
role	AssistanceRole	Yes	The role of the current user in the remote assistance session.
aliUid	string	Conditional	The tenant ID, used when a user initiates a remote assistance request. Required when `role` is `user`.
ticket	string	Conditional	An administrator parameter returned by the `GetCoordinateTicket` operation. Required when `role` is `admin`.
taskId	string	Conditional	An administrator parameter returned by the `GetCoordinateTicket` operation. Required when `role` is `admin`.
coId	string	Conditional	An administrator parameter returned by the `GetCoordinateTicket` operation. Required when `role` is `admin`.
remoteAssistance	string	Conditional	An administrator parameter. Default value: `on`. Required when `role` is `admin`.
accessKeyId	string	Conditional	An administrator parameter for keyboard and mouse control. Required when `role` is `admin`.
accessKeySecret	string	Conditional	An administrator parameter for keyboard and mouse control. Required when `role` is `admin`.

Enumerated types

OpenType

The way an EDS instance or a cloud application opens.

Value	Description
newTab	Opens the resource in a new tab.
inline	Opens the resource in an embedded iframe.
urlScheme	Opens the resource in the local native client. Requires Elastic Desktop Service client V6.2 or later.

ConnectType

Whether to connect to a cloud application or an EDS instance.

Value	Description
app	Connects to a cloud application.
desktop	Connects to an EDS instance.

ResourceType

Whether to open the local connection page or the Web Client.

Value	Description
local	Opens the local connection HTML page.

ReconnectType

The style of the reconnection dialog.

Value	Description
simple	Displays a simple loading window.
normal	Displays a countdown pop-up window.

ResolutionType

The default resolution used when a connection is initialized. A resolution that the user has already configured takes precedence.

Value	Description
A	Prioritizes speed. Uses the current window size.
B	Prioritizes quality. Uses the current window size multiplied by `window.devicePixelRatio`.

ChargeType

The billing method of an EDS instance.

Value	Description	Supported since
PostPaid	Pay-as-you-go billing.	1.4.0
PrePaid	Subscription billing.	1.4.0

Language

The language of the SDK prompts. Default value: zh-CN. To display prompts in English, set the value to en-US.

Value	Description
zh-CN	Chinese
en-US	English
ja-JP	Japanese

LoginType

The sign-in method for an EDS instance.

Value	Description
aliyunLogin	Signs in with an Alibaba Cloud account.
normalLogin	Signs in with an Elastic Desktop Service account.

ConnDecodeType

The decoding type of the stream.

Value	Description	Supported since
0	Software decoding.	1.2.0
1	Hardware decoding.	1.2.0
2	WebRTC decoding.	1.2.0

ProtocolType

The protocol used to connect to an EDS instance.

Value	Description	Supported since
ASP	An EDS instance that uses the Adaptive Streaming Protocol (ASP).	1.3.0
HDX	An EDS instance that uses the Citrix High Definition Experience (HDX) protocol.	1.3.0

AssistanceRole

The role type in a remote assistance session.

Value	Description	Supported since
user	A standard user.	1.3.0
admin	An administrator.	1.3.0
shared_user	A user of a shared EDS instance.	1.3.1
assistant	A collaborator.	1.4.0

Event and message types

SessionEventType

The event types of a session.

Value	Description	Supported since
getConnectionTicketInfo	Fires when the SDK initiates a connection to an EDS instance or a cloud application.	1.0.0
onConnected	Fires when the SDK connects to an EDS instance or a cloud application.	1.0.0
onDisConnected	Fires when the SDK disconnects from an EDS instance or a cloud application.	1.0.0
onRuntimeMsg	Fires when the SDK receives a message from the runtime.	1.1.0
networkData	Reports network performance metrics.	1.3.1
onError	Fires when an error occurs during the connection process.	1.4.1

GuestMsgType

The type of message sent to the guest OS.

Value	Description	Supported since
RUNTIME_API_MESSAGE	A message sent to the guest OS.	1.1.0

Error codes

onDisConnected: disconnection errors

The following table lists the errors that the onDisConnected event reports.

Name	Description	Code
ASP_CLIENT_DISCONNECT_CONNECT_ERROR	Connection error.	0
ASP_CLIENT_DISCONNECT_SOCKET_CLOSE	Socket closed.	1
ASP_CLIENT_DISCONNECT_WEBRTC_CLOSE	WebRTC closed.	2
ASP_CLIENT_DISCONNECT_CLOUD_APP_STOP	Cloud application stopped.	2001
ASP_CLIENT_DISCONNECT_CLIENT_PREEMPTION	Client preemption.	2002
ASP_CLIENT_DISCONNECT_GUEST_SHUTDOWN_REBOOT	Guest reboot.	2003
ASP_CLIENT_RTT_TIMEOUT	RTT timeout.	2200
ASP_CLIENT_NET_ERROR_IO	Network I/O error.	2201
ASP_CLIENT_UPDATE_TICKET_FAILED	Failed to update the ticket.	2202

onError: connection errors

The onError event reports errors raised during the connection process in the format {code: string, message: string, api: string}. The message field contains the request ID, and the api field identifies the request that failed. The following list shows the error codes.

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

The following error codes indicate that the logon credential (authCode) is no longer valid. When you receive one of these error codes, call GetConnectionTicket to obtain a new authCode and re-establish the connection to the Elastic Desktop Service instead of retrying the original request.

MissingLoginToken: the authCode or loginToken is missing or has expired. Obtain a new credential.
InvalidTimeStamp.Expired: the credential timestamp has expired. The authCode has exceeded its 10-minute validity period.

File transfer callback codes

The onTransferCallback function set in FileTransferConfig reports file transfer results with the following type and data:

type: 'result'

data: {Code, Message?: string, RequestId?: string, fileName?: string, fileSize?: string, fileId?: string}

The following table lists the values of Code.

Code	Description
ERROR_DRIVE_ID	Invalid drive ID.
ERROR_UPLOAD_PATH	Invalid upload path.
ERROR_UPLOAD_TYPE	Unsupported file type.
ERROR_FILE_EXISTS	A file with the same name already exists.
ERROR_TOKEN	The upload failed because the `loginToken` expired.
ERROR_SERVER	Service error. Contact the developer.
ERROR_DOWNLOAD	Failed to download the file.
SUCCESS_UPLOAD	Upload completed.