1. What is the Web SDK?
Alibaba Cloud Workspace SDK for Web allows you to connect to cloud computers and applications from Alibaba Cloud Workspace web clients. By integration with Alibaba Cloud Workspace SDK for Web, you can quickly set up your web client that suits your business requirements.
2. Quick start
All documents, SDKs, and client programs of this platform are for restricted use by you or your organization. You shall not share these resources to any third parties or other organizations without the prior consent of Alibaba Cloud.
Directory structure
├── WuyingWebDemo.html
├── WuyingWebSDK.js
├── HDXEngine.html
├── HDXLauncher.js
└── sdk
└── ASP
└── container.html Description: WuyingWebDemo.html is the sample SDK. WuyingWebSDK.js is the API file in the SDK that needs to be referenced in the frontend. HDXEngine.html is the file necessary for the Citrix Workspace. You can remove the file if you do not need it. HDXLauncher.js is the file necessary for the Citrix Workspace. You can remove the file if you do not need it. sdk is the resource file embedded by using an iframe.
3. API description
3.1 WebSDK
Name | Type | Description |
apiVersion | string | The version of the Web SDK. |
createSession(sessionId:string, sessionParams: SessionParam)
Creates a session for a cloud computer or application. This session is not the same as the allocated session in the backend.
Parameter | Type | Description |
id | string | The unique identifier of the session. This parameter is user-defined. |
sessionParams | SessionParam | The session parameters. |
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(): creates a session.
var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();stop(): stops a session.
var session = wuyingSdk.createSession('appstream', sessionParam);
session.start();
....
session.stop();addHandle(name: SessionEventType, callback: Function)
Adds listeners for events.
Parameter | Type | Description |
name | string | The type of the event to listen for. For more information, see the SessionEventType description. |
callback | Function | The 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)
Sends a message to an application in the guest OS.
Parameter | Type | Description |
msg | string | The message. |
appId | string | The application to which the message is sent. |
var msg = document.getElementById('sendMsgTypeData').value;
var appId = document.getElementById('sendMsgAppId').value;
session.sendRuntimeMsg(msg, appId);enableInput(param: boolean)
Enables or disables inputs from the mouse and keyboard.
Parameter | Type | Description |
param | bool | Specifies whether to enable inputs from the mouse and keyboard. |
enableKeyBoard(param: boolean)
Enables or disables the keyboard.
Parameter | Type | Description |
param | bool | Specifies whether to enable the keyboard. |
setClipboardEnabled(param: boolean)
Enables or disables the clipboard.
Parameter | Type | Description |
param | bool | Specifies whether to enable the clipboard. |
setMicrophoneEnabled(param: boolean)
Enables or disables the microphone.
Parameter | Type | Description |
param | bool | Specifies whether to enable the microphone. |
setInputEnabled(param: boolean)
Enables or disables inputs.
Parameter | Type | Description |
param | bool | Specifies whether to enable inputs. |
setTouchEnabled(param: boolean)
Enables or disables response to touch events.
Parameter | Type | Description |
param | bool | Specifies whether to enable response to touch events. |
downloadFile()
Opens a file download window in the cloud computer.
uploadFile(file: File)
Uploads a file.
Parameter | Type | Description |
file | File | The file to upload. |
enableDataIsland(enable: boolean)
Shows or hides the data island in runtime.
Parameter | Type | Description |
enable | boolean | Specifies whether to show the data island in runtime. |
uploadFileToPds(file: File[])
Uploads files to an enterprise drive.
You need to configure FileTransferConfig first, and then call session.uploadFileToPds to upload the files.
You can call onTransferCallback to receive the upload progress and error reports.
Parameter | Type | Description |
file | File | The files to upload. |
downloadFileFromPds(filePath: string)
Downloads files from an enterprise drive.
You need to configure FileTransferConfig first, and then call session.downloadFileFromPds to download the files.
Parameter | Type | Description |
filePath | string | The paths of the files to download from the enterprise drive. |
getScreenshot(callback: (blob: Blob) => any, immediate: boolean)
Obtains the current screenshot. You can specify callback in the method to obtain the blob object of the screenshot. If you set immediate to true, the screenshot is downloaded to your local device.
setResolution(width: number, height: number, degree: number)
Sets the display resolution for the cloud computer or application. The degree is in the clockwise direction.
Parameter | Type | Description |
width | number | The width. |
height | number | The height. |
degree | number | The degree. Valid values: 0 or 90. |
stopConnection()
Disconnects from a cloud computer or application.
getDesktopIdleTime(callback: (time: number) => any)
Queries the idle time of a cloud computer. Unit: ms.
setUiParams(param: UiConfig)
Configures the UI settings after a session is created, such as whether to display the menu or force the landscape mode.
Parameter | Type | Description |
param | UiConfig | The UI settings. |
var uiConfig = {
toolbar: {
visible: false,
},
rotateDegree: 90,
};
session.setUiParams(uiConfig);3.3 Parameter description
SessionParam
The following table describes parameters for creating a session.
Parameter | Type | Required | Description |
openType | OpenType | Yes | Specifies whether to open the session in an iframe or a new tab. |
iframeId | string | No | The iframe ID. This parameter is required if you set to open the session in an iframe. |
sdkPath | string | No | The path of the SDK file. If you do not specify this parameter, a relative path is used by default, such as ./ASP/container.html. |
resourceType | ResourceType | Yes | The resource type. Only on-premises resources are supported. |
connectType | ConnectType | Yes | Specifies whether to connect to a cloud computer or cloud application. |
isOverseas | boolean | No | Specifies whether to integrate the Web SDK in web pages outside China. Default value: false. |
userInfo | UserInfo | Yes | The information about the user logon session. |
regionId | string | Yes | The region where the cloud computer is located. This parameter is required if you set to connect to a cloud computer. |
appInfo | AppInfo | No | The information about the cloud application. |
desktopInfo | DesktopInfo | No | The information about the cloud computer. |
fileInfo | FileInfo | No | The information about the drive. |
uiConfig | UiConfig | No | The UI settings. |
fileTransferConfig | FileTransferConfig | No | The file transfer settings. |
logDisabled | bool | No | Specifies whether to disable Application Real-Time Monitoring Service (ARMS) monitoring. Default value: false. |
loginType | LoginType | No | The logon account type. By default, the Alibaba Cloud Workspace account is used for logon. |
networkAccessType | 'vpc' | No | The network access type. This parameter is left empty by default. VPC network access is supported. |
UserInfo
The following table describes logon session-related parameters. We recommend that you preferentially use authCode.
Parameter | Type | Required | Description |
authCode | string | Yes | The logon credential that can be used only once, which has the highest priority. |
ticket | string | Yes | The ticket can be directly passed in to establish a connection in Web SDK versions later than 1.4.7. |
loginToken | string | Yes | The information about the user logon session (deprecated). |
sessionId | string | Yes | The information about the user logon session (deprecated). |
AppInfo
The following table describes parameters about a connected cloud application.
Parameter | Type | Required | Description |
appId | string | Yes | The ID of the connected cloud application. |
appVersion | string | Yes | The version of the connected cloud application. |
loginRegionId | string | Yes | The region where the cloud application resources reside. |
connConfig | ConnConfig | No | The connection parameters. |
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 where the cloud application resources reside. |
productType | string | No | The type of the delivery group. Default value: 'CloudApp'. |
DesktopInfo
The following table describes parameters about a connected cloud computer.
Parameter | Type | Required | Description |
desktopId | string | Yes | The ID of the connected cloud computer. |
realDesktopId | string | No | This parameter is required if you connect to a cloud computer in a cloud computer pool. |
protocolType | ProtocolType | No | The protocol type used by the connected cloud computer. |
loginRegionId | string | Yes | The region where the cloud computer resources reside. |
connConfig | ConnConfig | No | The connection parameters. |
assistanceConfig | AssistanceConfig | No | The remote assistance configuration. If you do not configure this parameter, remote assistance is not enabled. |
creationTime | string | No | The time when the cloud computer was created. Specify the time in UTC. |
expiredTime | string | No | The time when the cloud computer expires. Specify the time in UTC. |
chargeType | ChargeType | No | The billing method of the cloud computer. |
FileInfo
The following table describes parameters for opening a drive. Note: You can specify the externalDomainId, externalDriveId, and externalUserId parameters to upload files to a hosted drive offered by Alibaba Cloud Photo and Drive Service. In this case, you do not need to specify the driveId parameter.
Parameter | Type | Required | Description |
driveType | string | Yes | The drive type, which can be PDS only. |
driveId | string | Yes | The drive ID. |
externalDomainId | string | Yes | The ID of the domain where the drive offered by Photo and Drive Service resides. |
externalDriveId | string | Yes | The ID of the drive offered by Photo and Drive Service. |
externalUserId | string | Yes | The external user ID. |
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 located. Example: cn-hangzhou. |
FileTransferConfig
The following table describes parameters for file upload and download.
Parameter | Type | Required | Description |
type | string | No | The drive type, which can only be PDS. |
driveId | string | No | The drive ID. |
uploadPath | string | No | The path to which the file is uploaded. |
uploadType | string[] | No | The type of the file to upload. For more information, see the MIME TYPE definition. |
onTransferCallback | function | No | The callback for data transfer status. (type, data => any) |
TransferData
The following table describes the information received by onTransferCallback.
Parameter | Description |
fileName | The file name. |
fileSize | The file size. |
fileId | The file ID. |
progress | The file upload progress. |
cancelFn | Cancels the upload callback. If you cancel the callback during upload, the file upload is canceled. |
Callback message code
type: 'result'data: {Code, Message?: string, RequestId?: string, fileName?: string, fileSize?: string, fileId?: string}
Parameter | Description |
ERROR_DRIVE_ID | Incorrect drive ID. |
ERROR_UPLOAD_PATH | Incorrect upload path. |
ERROR_UPLOAD_TYPE | Invalid file type. |
ERROR_FILE_EXISTS | A file with the same name already exists. |
ERROR_TOKEN | Upload failed due to invalid loginToken. |
ERROR_SERVER | Service error. Contact development personnel. |
ERROR_DOWNLOAD | An error occurred during file download. |
SUCCESS_UPLOAD | Uploaded. |
UiConfig
The following table describes the parameters for UI settings.
Parameter | Type | Required | Description |
toolbar | ToolBarConfig | No | The toolbar settings in the connection window. |
exitCheck | bool | No | Specifies whether to enable a confirmation dialog box when you attempt to exit the current page. By default, this option is enabled. |
rotateDegree | number | No | Specifies whether to force the landscape mode. Valid values: 0 and 90. Value 90 indicates yes. |
vconsoleVisiable | bool | No | Specifies whether to display the VConsole debugging box. |
debugPanelVisiable | bool | No | Specifies whether to display the box that contains information such as the frame rate and bitrate. |
reconnectType | ReconnectType | No | The style of the dialog box for reconnection. |
defaultResolution | ResolutionType | No | The default screen resolution upon the first connection. Default value: 'A'. |
language | Language | No | The language used for internal pop-up prompts. The default language is Chinese. |
ToolBarConfig
The following table describes parameters for toolbar settings.
Parameter | Type | Required | Description |
visible | bool | No | Specifies whether to display the toolbar. |
noMenu | bool | No | Specifies whether to allow opening the right-click menu by using DesktopAssistant. Default value: false. This feature is supported in Web SDK versions later than 1.4.20. |
ConnConfig
The following table describes the connection parameters.
Parameter | Type | Required | Description |
decodeType | ConnDecodeType (numeric enumeration) | No | The encoding type. |
playSoundBackground | bool | No | Specifies whether to continue playing sound after switching the background. |
AssistanceConfig
The following table describes parameters for initiating remote assistance. If a remote assistance request is initiated by an administrator, the connection is one-off only. Given that the ticket can be used repeatedly, you must clear the ticket once a remote assistance connection ends to prevent subsequent reconnections.
Parameter | Type | Required | Description |
role | AssistanceRole | Yes | The role who initiated remote assistance. |
aliUid | string | No | The ID of the end user. This parameter is required when the role parameter is set to user. |
ticket | string | No | This parameter is required when the role parameter is set to admin. You can obtain the value by calling the GetCoordinateTicket operation. |
taskId | string | No | This parameter is required when the role parameter is set to admin. You can obtain the value by calling the GetCoordinateTicket operation. |
coId | string | No | This parameter is required when the role parameter is set to admin. You can obtain the value by calling the GetCoordinateTicket operation. |
remoteAssistance | string | No | This parameter is required when the role parameter is set to admin. Default value: on. |
accessKeyId | string | No | Used to control the keyboard and mouse. This parameter is required when the role parameter is set to admin. |
accessKeySecret | string | No | Used to control the keyboard and mouse. This parameter is required when the role parameter is set to admin. |
Parameters of the enumerated type
OpenType
The following table enumerates the options to open a connected cloud computer or application.
Option | Description |
newTab | Opens a connected cloud computer or application in a new tab. |
inline | Opens a connected cloud computer or application on an iframe page. |
urlScheme | Opens a connected cloud computer or application on a local native client. This option requires the Alibaba Cloud Workspace client of a version later than 6.2 installed. |
ConnectType
The following table enumerates whether to connect to a cloud computer or a cloud application.
Option | Description |
app | Connects to a cloud application. |
desktop | Connects to a cloud computer. |
ResourceType
The following table enumerates the resource type to be accessed.
Option | Description |
local | The HTML page loaded from the local PC. |
ReconnectType
The following table enumerates the options to configure the prompt pop-up window.
Option | Description |
simple | Uses simple loading. |
normal | Uses a countdown pop-up window. |
ResolutionType
The following table enumerates the options to set the default resolution during initialization of a connection. A history resolution setting is preferentially used during a connection.
Option | Description |
A | Uses the current window size to ensure loading speed. |
B | Uses the resolution of the current window size multiplied by window.devicePixelRatio to ensure display quality. |
ChargeType
The following table enumerates the billing methods of a cloud computer.
Option | Description | Available from |
PostPaid | The pay-as-you-go billing method. | 1.4.0 |
PrePaid | The subscription billing method. | 1.4.0 |
Language
The following table enumerates the language options. Default value: zh-CN.
Option | Description |
zh-CN | Chinese. |
en-US | English. |
ja-JP | Japanese. |
LoginType
The following table enumerates the methods to log on to a cloud computer.
Option | Description |
aliyunLogin | Logon with an Alibaba Cloud account. |
normalLogin | Logon with an Alibaba Cloud Workspace account. |
Events
SessionEventType
The following table describes session-related events.
Event | Description | Available from |
getConnectionTicketInfo | Attempt to connect to a cloud computer or application. | 1.0.0 |
onConnected | Successful connection to a cloud computer or application. | 1.0.0 |
onDisConnected | Disconnection from a cloud computer or application. | 1.0.0 |
onRuntimeMsg | Message transmission to the SDK in the runtime. | 1.1.0 |
networkData | Configuration of network performance parameters. | 1.3.1 |
onError | Error handling during a connection. | 1.4.1 |
Message type to the guest OS
GuestMsgType
The following table describes the type of the message sent to the guest OS.
Name | Description | Available from |
RUNTIME_API_MESSAGE | The message sent to the guest OS. | 1.1.0 |
Stream decoding type
ConnDecodeType
Name | Description | Available from |
0 | Software decoding. | 1.2.0 |
1 | Hardware decoding. | 1.2.0 |
2 | WebRTC. | 1.2.0 |
Cloud computer-related
ProtocolType
Name | Description | Available from |
ASP | Adaptive Streaming Protocol (ASP). | 1.3.0 |
HDX | Citrix HDX. | 1.3.0 |
Remote assistance-related
AssistanceRole
Name | Description | Available from |
user | The user. | 1.3.0 |
admin | The administrator. | 1.3.0 |
shared_user | The user with which you share the desktop for collaboration. | 1.3.1 |
assistant | The user who join the collaboration. | 1.4.0 |
3.4 Error codes
The following table describes error messages reported in case of a disconnection event.
Error message | Description | Code |
ASP_CLIENT_DISCONNECT_CONNECT_ERROR | Disconnected. | 0 |
ASP_CLIENT_DISCONNECT_SOCKET_CLOSE | Socket connection closed. | 1 |
ASP_CLIENT_DISCONNECT_WEBRTC_CLOSE | WebRTC connection closed. | 2 |
ASP_CLIENT_DISCONNECT_CLOUD_APP_STOP | Cloud application stopped. | 2001 |
ASP_CLIENT_DISCONNECT_CLIENT_PREEMPTION | Resource preempted. | 2002 |
ASP_CLIENT_DISCONNECT_GUEST_SHUTDOWN_REBOOT | Guest OS restarted. | 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 |
Error messages received by onError during a connection
The message is in the following format: {code: string, message: string, api: string}, in which message contains requestId, and api is the request that triggers an error. The following table lists the error codes.
Error 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 |