Elastic Desktop Service:iOS SDK

1. Release notes

2. Usage of the ASP SDK for iOS

2.1 OS

iOS version: iOS 10.0 or later

If you want to use peripheral mouses and keyboards, use iOS 13.4 or later.

2.2 Main header files

2.3 SDK integration and usage

2.3.1 SDK integration

Second-party: Integrate SDK by using a pod

1. Add a library dependency, such as pod 'ASPEngineSDK' '3.1.2022071802', to the Podfile file.

2. Prepare a tpod environment.

You need to install tpod only once.

sh <(curl http://tpm.taobao.net/taobaoSetup.sh) # This may take some time. Wait until it completes.

3. Execute the pod project.

tpod install --verbose # This may take some time. Wait until it completes. If the execution fails, delete the Pods directory and try again.
tpod update --fast-mode --build-target=Debug,Release # Update PODS on your local device.

Third-party: Integrate SDK by using a framework

1. Prepare the following framework for device debugging:

asp-sdk-publish/sdk/asp-engine/ios/ASPEngineSDK/3.1.2022071802/ASPEngineSDK.framework.zip

2. Prepare the following framework for simulator debugging:

asp-sdk-publish/sdk/asp-engine/ios/ASPEngineSDK_Simulator/3.1.2022071803/ASPEngineSDK.framework.zip

3. Obtain the version number of SDK libraries. In the preceding framework files, 3.1.2022071802 and 3.1.2022071803 are the version numbers of the generated SDK libraries.

4. Copy a framework to your project.

5. Link the SDK to your project by adding the framework to the project.

target --> Build Phases --> Link Binary With Libraries --> + --> Add Other -- Add Files --> Select a framework

6. Embed the framework in your project without signing.

target --> General --> Frameworks, Libraries, and Embedded Content --> Find the ASPEngineSDK.framework --> Embed Without Signing

2.3.2 SDK permissions

You need to grant the permissions required for ASPEngineSDK in the info.plist file of the project.

1. Microphone permissions

Privacy - Microphone Usage Description

2. Camera permissions

Privacy - Camera Usage Description

2.3.3 SDK signatures

SDK libraries are dynamic libraries. When you use a device for debugging or publishing applications to App Store, signatures are required.

1. Configure a signature ID in the KEY file

You can refer to the KEY configurations in the demo project directory. By default, a signature ID exists in the KEY file. You can use one of the following methods to modify the signature ID in the KEY file:

1.1 Use CLI

In the command window, run the cd command to go to the desired project directory to proceed. Then, run the following command:

echo "8AEF20DC6E0CBFF4FA852118BCDD6D507F5764ED" > KEY

1.2 Use a text editor

In the project, find the KEY file, open the file as a text file and modify the file.

2. Obtain a signature ID

You can run the following command to check the signature ID of a certificate installed on your local device.

security find-identity -v -p codesigning

If you do not have any certificate installed on your local device, log on to the Apple Developer official site with an Apple Developer account and download the profile of the desired certificate. After you download the certificate, right-click the certificate and select Get Info from the shortcut menu to show its profile. Then, all certificates that are related to the profile are displayed. Then, you need to find information about the certificate and copy the value of the SHA-1 parameter as the signature ID of the certificate.

3. Configure a certificate on the Signing & Capabilities tab

You must clear the existing signature ID in the KEY file. Then, you can configure certificates on the Signing & Capabilities tab for targets of the project.

4. Add a signature shell script (required only for device debugging)

target --> Build Phases --> + --> New Run Script Phase --> Enter a shell script content (refer to the sample signature in the following section) --> Add the KEY file, click the Add button (+) in the Input Files section, and then enter $(SRCROOT)/KEY.
Note: Run Script must appear under Embed Frameworks.

5. Sample signature

set -e
SHELL_PATH="${PROJECT_DIR}/ASPDemo/Lib/ASPEngineSDK/3.1.2022063002-SNAPSHOT/ASPEngineSDK.framework/link_and_sign.sh"
while read -r line; do
exit 0
done < ${SCRIPT_INPUT_FILE_0}
echo "===> Signing using $line"
/bin/bash -c "${SHELL_PATH}"\ "${TARGET_BUILD_DIR}"\ "${FRAMEWORKS_FOLDER_PATH}"\ "${line}"

2.3.4 Precautions

If you need to disable Bitcode, run the following command:

target --> Build Settings --> Build Options --> Enable Bitcode --> No

2.3.5 SDK samples using the core APIs

- (void)viewDidLoad {
    [super viewDidLoad];

    # Set the callback for log outputs. SDK logs are output based on the callback.
    [ASPStreamView setASPEngineLogDelegate:[ASPDemoLog sharedInstance]];
    # Create an object and start to connect to a cloud computer.
    ASPStreamView* streamView = [ASPStreamView buildStreamView];
    [streamView setASPEngineDelegate:self];
    if (self.connParam.connTicket) {
        ASPConnTicket* ticketParam = [[ASPConnTicket alloc] init];
        ticketParam.connTicket = self.connParam.connTicket;
        ticketParam.useVpc = false;
        ticketParam.enableStatistics = true;
        ticketParam.desktopId = self.connParam.desktopId;
        [streamView startWithTicket:ticketParam];
    } else {
        ASPConnParam* connParam = [[ASPConnParam alloc] init];
        connParam.connIp = self.connParam.connIp;
        connParam.connPort = self.connParam.connPort;
        connParam.connUdpPort = self.connParam.connUdpPort;
        connParam.connToken = self.connParam.connToken;
        connParam.enableTls = self.connParam.enableTls;
        connParam.desktopId = self.connParam.desktopId;
        connParam.enableStatistics = true;
        [streamView start:connParam];
    }
    self.streamView = streamView;
    [self.view addSubview:streamView];
    // View the callback for event tracking.
    [self.streamView setASPEngineStatisticsDelegate:self];
}

- (void)onConnectionSuccess {
    NSLog(@"Callback for successful connection to the cloud computer");
}

- (void)onDisconnected:(int)reason {
    //reason 2000-Sucessful disconnection 2001–2009-Status code for disconnection from the cloud computer by an end user 2001–2005-If you want to learn the code description, see Error codes in this topic. 2006–2009-Undefined
    NSLog(@"Callback for successful disconnection from the cloud computer");
}

- (void)onReconnect {
    NSLog(@"Callback for automatic reconnection to the cloud computer");
}

- (void)onConnectionFailureWithErrCode:(int)errCode errMsg:(NSString *)errMsg {
    NSLog(@"Callback for errors of the cloud computer");
}

- (void)onEngineErrorWithErrCode:(int)errCode errMsg:(NSString *)errMsg {
    NSLog(@"An error occurs in the internal logic of ASPEngineSDK");
}

- (void)onStatisticsInfoUpdate:(StatisticsInfo)info {
    NSLog(@"Callback for event tracking");
}

3. Operations

3.1 ASPEngineSDK

3.1.1 ASPStreamView.h

3.1.1.1 init

The method for initialization.

+ (instancetype)buildStreamView;

3.1.1.2 start

The method to start cloud computers. To connect to a cloud computer, you must specify the specified server connection parameters.

i. Start the streaming service by using the server session obtained from PaaS

- (void)startWithTicket:(ASPConnTicket*) ticketParam;

ASPConnTicket parameters

ii. Start the streaming service in the cloud by using the specified server connection parameters.

This method is commonly used in routine debugging and suitable for scenarios in which the ASP server can be directly connected by bypassing a gateway (or when you obtain the address of a gateway and the token to access the gateway).

- (void)start:(ASPConnParam*) connParam;

ASPConnParam parameters

3.1.1.3 stop

The method to stop a cloud computer.

- (int)stop;

3.1.1.4 dispose

The method to delete a cloud computer.

- (void)dispose;

3.1.1.5 delegate

// The delegating object to connect to a cloud computer.
@property (nonatomic, weak) id<ASPEngineDelegate> engineDelegate;
// The callback for resolution change.
@property (nonatomic, weak) id<ASPEngineResolutionUpdateDelegate> resolutionUpdateDelegate;
// The callback for pointer movement.
@property (nonatomic, weak) id<ASPEngineCursorDelegate> cursorDelegate;
// The callback for the screen orientation change of a cloud computer.
@property (nonatomic, weak) id<ASPEngineOrientationUpdateDelegate> orientationUpdateDelegate;
// The callback for event tracking.
@property (nonatomic, weak) id<ASPEngineStatisticsDelegate> statisticsDelegate;
// The callback for input events triggered by input method editor (IME).
@property (nonatomic, weak) id<ASPEngineIMEDelegate> imeDelegate;
// The callback for log outputs. We recommend that you use call one cloud computer only.
+ (void)setASPEngineLogDelegate:(id<ASPEngineLogDelegate>)delegate;
+ (void)unsetASPEngineLogDelegate;

3.1.1.6 enableStatistics

The method to enable event tracking.

- (BOOL)enableStatistics:(BOOL) enabled;

3.1.1.7 enableMouseMode

The method to enable the mouse mode.

- (BOOL)enableMouseMode:(BOOL)enabled;

3.1.1.8 enableDump

The method to dump debugging data to files. This operation consumes performance and is used for debugging only. Do not enable this feature in production environments.

@property (nonatomic, assign) BOOL enableDump;

3.1.1.9 sendKeyboardEvent

The method to send a keyboard event.

- (BOOL)sendKeyboardEvent: (ASPKeyEvent) event;

3.1.1.10 simulateMouseClick

The method to simulate a mouse click.

// leftButton specifies whether you want to simulate a left click or right click. Cursor position x:0 y:0
- (BOOL)simulateMouseClick:(BOOL)leftButton;
- (BOOL)simulateMouseClick:(BOOL)leftButton x:(float)x y:(float)y;

3.1.1.11 setVideoProfileWithWidth

The method to configure the resolution of a cloud computer.

- (void)setVideoProfileWithWidth:(int)width height:(int)height fps:(int)fps;

3.1.1.12 setMute

The method to mute audio.

@property (nonatomic, assign) BOOL mute;

3.1.2 ASPEngineSDK.h

3.1.2.1 start

The method to start a cloud computer. To connect to a cloud computer, you must specify the specified server connection parameters.

i. Start the streaming service by using the ServerSession string obtained from PaaS

- (void)startWithTicket:(ASPConnTicket*) ticketParam;

ASPConnTicket parameters

ii. Start the streaming service in the cloud by using the specified server connection parameters.

This method is commonly used in routine debugging and suitable for scenarios in which the ASP server can be directly connected by bypassing a gateway (or when you obtain the address of a gateway and the token to access the gateway).

- (void)start:(AspConnParam*) connParam;

ASPConnParam parameters:

3.1.2.2 stop

The method to disconnect from a cloud computer.

- (int)stop;

3.1.2.3 pause

The method to suspend a cloud computer.

- (void)pause;

3.1.2.4 resume

The method to resume a cloud computer.

- (void)resume;

3.1.2.5 setRenderView

The method to configure the view container of a cloud computer.

- (void)setRenderView:(UIView*) view;

3.1.2.6 dispose

The method to delete a cloud computer.

- (void)dispose;

3.1.2.7 enableRTC

The method to enable RTC transmission.

- (void)enableRTC:(bool) enabled;

3.1.2.8 enableVDAagentCheck

The method to check VDAgent.

- (void)enableVDAagentCheck:(bool) enabled;

3.1.2.9 enableStatistics

The method to enable event tracking.

- (BOOL)enableStatistics:(BOOL) enabled;

3.1.2.10 dump

The method to dump debugging data to files. This operation consumes performance and is used for debugging only. Do not enable this feature in production environments.

- (void)setDumpPath:(NSString *)path;

@property (nonatomic, assign) BOOLenableDump;

3.1.2.11 delegate

The method to use callbacks of different kinds.

// The callback for cloud computer connection.
@property (nonatomic, weak) id<ASPEngineDelegate> engineDelegate;
// The callback for resolution change.
@property (nonatomic, weak) id<ASPEngineResolutionUpdateDelegate> resolutionUpdateDelegate;
// The callback for pointer movement.
@property (nonatomic, weak) id<ASPEngineCursorDelegate> cursorDelegate;
// The callback to change the screen orientation of a cloud computer.
@property (nonatomic, weak) id<ASPEngineOrientationUpdateDelegate> orientationUpdateDelegate;
// The callback for event tracking.
@property (nonatomic, weak) id<ASPEngineStatisticsDelegate> statisticsDelegate;
// The callback for input events triggered by input method editor (IME).
@property (nonatomic, weak) id<ASPEngineIMEDelegate> imeDelegate;
// The callback for clipboard usage.
@property (nonatomic, weak) id<ASPEngineClipboardDelegate> clipboardDelegate;
// The callback for the pinch-to-zoom feature.
@property (nonatomic, weak) id<ASPEngineGestureDelegate> gestureDelegate;
// The callback for log outputs.
@property (class, nonatomic, weak) id<ASPEngineLogDelegate> logDelegate;

3.1.2.12 setVideoProfileWithWidth

The method to configure the resolution of a cloud computer.

- (void)setVideoProfileWithWidth:(int)width height:(int)height fps:(int)fps; // The destination frames per second (FPS) configured for video streams takes effect soon.

3.1.2.13 touch

The method to send an input event occurred on the touch screen of a cloud computer.

- (void)sendTouchEvent:(ASPTouchEvent*)event touchAction:(ASPTouchAction)action;

- (void)sendTouchEvents:(NSArray<ASPTouchEvent*>*) eventArray touchAction:(ASPTouchAction)action index:(int)index;

3.1.2.14 keyboard

The method to send a keyboard event.

- (BOOL)sendKeyboardEvent: (ASPKeyEvent) event;

// Caps/Num/Scroll Lock
- (void)sendKeyboardLockModifiers: (int) modifers;

3.1.2.15 mouse

The method to enable the mouse mode.

- (BOOL)enableMouseMode:(BOOL) enabled;

The method to send a mouse-related event.

- (void)sendMouseButtonEvent: (ASPMouseButtonEvent)event;

- (void)sendMouseMoveEvent: (ASPMouseMoveEvent)event;

- (void)sendMouseWheelEvent:(int)delta buttonState:(ASPMouseButtonMask)buttonState;

3.1.2.16 ime

The method to send an input event.

- (void)setImePreedit: (NSString*)preeditStr;

- (void)setImeCommit: (NSString*)commitStr;

3.1.2.17 clipboard

The method to send a clipboard event

- (void)sendClipboardType:(int)type;

type parameters:

enum ASPEngineClipboardType {
    ASPENGINE_CLIPBOARD_NONE = 0,
    ASPENGINE_CLIPBOARD_UTF8_TEXT,
    ASPENGINE_CLIPBOARD_IMAGE_PNG,  /* All clients with image support should support this one */
    ASPENGINE_CLIPBOARD_IMAGE_BMP,  /* optional */
    ASPENGINE_CLIPBOARD_IMAGE_TIFF, /* optional */
    ASPENGINE_CLIPBOARD_IMAGE_JPG,  /* optional */
};

3.1.2.18 ASPEngineDelegate

The callback for cloud computer connection.

@protocol ASPEngineDelegate <NSObject>
// An internal engine error occurs.
- (void)onEngineErrorWithErrCode:(int)errCode errMsg:(NSString*)errMsg;
// A cloud computer is connected.
- (void)onConnectionSuccess;
// A cloud computer fails to be connected.
- (void)onConnectionFailureWithErrCode:(int)errCode errMsg:(NSString*)errMsg;
// A cloud computer is disconnected.
- (void)onDisconnected:(int)reason;
// The first frame callback for a cloud computer.
- (void)onFirstFrameRendered:(long)timeCostMS;
// The cloud computer is being reconnected.
- (void)onReconnect;

@end

3.1.2.19 ASPEngineResolutionUpdateDelegate

The callback for the resolution change of a cloud computer.

@protocol ASPEngineResolutionUpdateDelegate <NSObject>

- (void)onResolutionUpdateWithOldWidth:(int)oldWidth oldHeight:(int)oldHeight
width:(int)width height:(int)height;

@end

3.1.2.20 ASPEngineCursorDelegate

The callback for the pointer movement on a cloud computer.

@protocol ASPEngineCursorDelegate <NSObject>
// When the pointer scheme changes
- (void)onCursorBitmapUpdateWithHotX:(int)hotX hotY:(int)hotY width:(int)width
height:(int)height rgba:(char*)rgba;
// When the pointer status is reset
- (void)onCursorReset;
// When the pointer is hidden
- (void)onCursorHide;
// When the pointer moves
- (void)onCursorMoveWithX:(int)x y:(int)y;
@end

3.1.2.21 ASPEngineOrientationUpdateDelegate

The callback for listening on the screen orientation events.

@protocol ASPEngineOrientationUpdateDelegate <NSObject>

- (void)onOrientationUpdateWithOldOrientation:(int)oldOrientation newOrientation:(int)newOrientation;

@end

3.1.2.22 ASPEngineStatisticsDelegate

The callback for listening on performance and key running status.

@protocol ASPEngineStatisticsDelegate <NSObject>

- (void)onStatisticsInfoUpdate:(ASPStatisticsInfo *)info;

@end

ASPStatisticsInfo parameters

@interface ASPStatisticsInfo : NSObject

@property (nonatomic, assign) int mReceiveFps; // The number of frames per second (FPS) received on the client.
@property (nonatomic, assign) int mRenderFps; // The number of frames per second in rendering on the client.
@ property (nonatomic, assign) double mDownstreamBandwithMBPerSecond; // The downstream bandwidth. Unit: MB/s.
@property (nonatomic, assign) double mUpstreamBandwithMBPerSecond; // The upstream bandwidth. Unit: MB/s.
@property (nonatomic, assign) long mP2pFullLinkageLatencyMS; // The end-to-end latency. Unit: ms.
                                           // Currently, this value can be accurately represented only when a specific application is used in the guest OS.
@ property (nonatomic, assign) long mNetworkLatencyMS; // The round-trip time (RTT) latency. Unit: ms.
@property (nonatomic, assign) long mPingGatewayRtt;   // The RTT latency used for pinging a gateway. Unit: ms.
@ property (nonatomic, assign) double mLostRate; // The packet loss rate.
@property (nonatomic, assign) long mServerRenderLatencyMS; // The latency used for rendering on the server. Unit: ms.
@property (nonatomic, assign) long mServerEncoderLatencyMS; // The latency used for coding on the server. Unit: ms.
@ property (nonatomic, assign) long mServerTotalLatencyMS; // The total latency on the server. Unit: ms.
@ property (nonatomic, assign) long accumulateBandwidth; // The total bandwidth.
@ property (nonatomic, copy ) NSString *protocolType; // The stream protocol type.

@property (nonatomic, copy  ) NSDictionary *infoDic;

@end

3.1.2.23 ASPEngineIMEDelegate

The callback for listening on the focus change in an input field and the position change of the IME UI element.

@protocol ASPEngineIMEDelegate <NSObject>

// When an input field gets focus or lose focus
- (void)onIMEFocusUpdate:(bool)hasFocus;
// When the position of the IME UI element changes
- (void)onIMELocationUpdateWithX:(int)x y:(int)y;

@end

3.1.2.24 ASPEngineClipboardDelegate

The callback for listening on the clipboard that reads and writes data from and to the client.

@protocol ASPEngineClipboardDelegate <NSObject>

// When data is pasted from a local device to a cloud computer, read data from the device.
- (void)onClipBoardRead:(int)engineId type:(int *)type data:(uint8_t**)data size:(int *) size selection:(uint8_t)selection;
// When data is copied from a cloud computer to a local device, write data to the device.
- (void)onClipBoardWrite:(int)engineId type:(int)type data:(uint8_t*)data size:(int)size;

@end

3.1.2.25 ASPEngineGestureDelegate

The callback for listening on the pinch-to-zoom and move gestures.

@protocol ASPEngineGestureDelegate <NSObject>

- (void)onScale:(float)sx sy:(float)sy;
- (void)onTranslate:(float)tx ty:(float)ty;

@end

3.1.2.26 ASPEngineLogDelegate

The callback for log outputs.

@protocol ASPEngineLogDelegate <NSObject>

- (void)onLogMessage:(NSString*)msg tag:(NSString*)tag level:(AspLogLevel)level;

@end

3.1.2.27 mute

The method to mute audio.

@property (nonatomic, assign) BOOL mute;

4. Error codes

5. Attachments

5.1 Demo

iOSDemo.zip

5.2 SDK

iOSSDK.zip