iOS SDK

1. Release notes

2. ASP iOS SDK

2.1 Prerequisites

Minimum supported iOS version: 10.0

Peripheral mouse and keyboard support requires iOS 13.4 or later, as this version includes the necessary system interfaces.

2.2 Main file

2.3 SDK integration and usage

2.3.1 SDK integration

Second-party: Integrate SDK via Pod

1. Add the following library dependency to your Podfile: pod 'ASPEngineSDK', '3.1.2022071802'

2. Tpod environment

You only need to install tpod once.

sh <(curl http://tpm.taobao.net/taobaoSetup.sh) # This may take a while.

3. In the root directory of the pod project, run the command.

tpod install --verbose # This may take a while. If it fails, delete the pods directory and run it again.
tpod update --fast-mode --build-target=Debug,Release # Update local pods.

Third-party: Framework integration

1. Physical device build

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

2. Emulator package

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

3. The 3.1.2022071802 and 3.1.2022071803 directories are the version numbers of the generated SDK library.

4. Copy the framework from either the real device package or the simulator package to your project.

5. Link SDK

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

6. Configure embedding

target --> general --> Frameworks, Libraries, and Embedded Content --> ASPEngineSDK.framework --> Embed Without Signing

2.3.2 SDK permissions

Configure the permissions required by ASPEngineSDK in your project's info.plist file.

1. Microphone permission

Privacy - Microphone Usage Description

2. Camera permission

Privacy - Camera Usage Description

2.3.3 SDK signature

As a dynamic library, the SDK requires code signing for on-device debugging or for publishing to the App Store.

1. Key file signing

Signing is configured in the key file, located in your demo project directory. This file is empty by default. To enable signing, add a signature ID to the file as follows:

1.1 Command Modification

In a command window, navigate to the project directory and run the following command:

echo "8AEF20DC6E0CBFF4FA852118BCDD6D507F5764ED" > KEY

1.2 Modifying Manually

In the project, find the KEY file and edit it in a text editor.

2. Get signature ID

Run the following command to find the signing ID of your local certificate:

security find-identity -v -p codesigning

If you don't have the certificate installed locally, sign in to your Apple Developer Account and download the corresponding provisioning profile. After downloading the file, right-click it and select "Get Info" from the context menu. In the preview section, you will see the certificate details associated with this provisioning profile. Locate the correct certificate. The value next to "SHA-1" is the signing ID you need.

3. Signing and capabilities

Clear the signature ID in the key file, then configure the certificate for your project's target under Signing & Capabilities.

4. Add a signature shell

target --> Build Phases --> + --> New Run Script Phase --> enter the shell script content (refer to the signing example) --> under Input Files, click + and add $(SRCROOT)/KEY
Note: Position the Run Script phase below the Embed Frameworks phase.

5. Signature example

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 Project configuration

Disable Bitcode

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

2.3.5 SDK core API examples

- (void)viewDidLoad {
    [super viewDidLoad];

    // Set the log callback. SDK logs are output through this callback.
    [ASPStreamView setASPEngineLogDelegate:[ASPDemoLog sharedInstance]];
    // Create an instance and start a connection to the cloud desktop.
    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];
    // Set the delegate for statistics callbacks.
    [self.streamView setASPEngineStatisticsDelegate:self];
}

- (void)onConnectionSuccess {
    NSLog(@"Cloud desktop connection successful.");
}

- (void)onDisconnected:(int)reason {
    // The `reason` code 2000 indicates a successful disconnection. Codes 2001–2009 represent server-initiated disconnections. For codes 2001-2005, see the error descriptions below. Codes 2006-2009 are reserved for future use.
    NSLog(@"Cloud desktop disconnected.");
}

- (void)onReconnect {
    NSLog(@"Cloud desktop is reconnecting automatically.");
}

- (void)onConnectionFailureWithErrCode:(int)errCode errMsg:(NSString *)errMsg {
    NSLog(@"Cloud desktop connection failed.");
}

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

- (void)onStatisticsInfoUpdate:(StatisticsInfo)info {
    NSLog(@"Statistics received.");
}

3. API

3.1 ASPEngineSDK

3.1.1 ASPStreamView.h

3.1.1.1 init

initialization API

+ (instancetype)buildStreamView;

3.1.1.2 Start

Connect to EDS using the server connection parameters.

1) Start the streaming service using the server session obtained from PaaS.

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

ASPConnTicket parameters

2) Start the cloud streaming service using the specified server connection parameters.

This method is for day-to-day debugging when you can connect directly to the ASP Server, either by bypassing the gateway or by using a known gateway address and an accessible token.

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

ASPConnParam:

3.1.1.3 Stop

Disconnect from your EDS session.

- (int)stop;

3.1.1.4 Dispose

Deletes the cloud desktop.

- (void)dispose;

3.1.1.5 delegate

// Callbacks for cloud desktop connection
@property (nonatomic, weak) id<ASPEngineDelegate> engineDelegate;
// Callbacks for resolution changes
@property (nonatomic, weak) id<ASPEngineResolutionUpdateDelegate> resolutionUpdateDelegate;
// Callbacks for the cursor
@property (nonatomic, weak) id<ASPEngineCursorDelegate> cursorDelegate;
// Callbacks for orientation changes
@property (nonatomic, weak) id<ASPEngineOrientationUpdateDelegate> orientationUpdateDelegate;
// Callbacks for event tracking
@property (nonatomic, weak) id<ASPEngineStatisticsDelegate> statisticsDelegate;
// Callbacks for the input method editor (IME)
@property (nonatomic, weak) id<ASPEngineIMEDelegate> imeDelegate;
// Log callbacks. It is recommended to use a singleton for the delegate.
+ (void)setASPEngineLogDelegate:(id<ASPEngineLogDelegate>)delegate;
+ (void)unsetASPEngineLogDelegate;

3.1.1.6 enableStatistics

Enable instrumentation.

- (BOOL)enableStatistics:(BOOL) enabled;

3.1.1.7 enableMouseMode

Determines whether mouse mode is enabled.

- (BOOL)enableMouseMode:(BOOL)enabled;

3.1.1.8 enableDump

Specifies whether to enable dump. Because this feature impacts performance, it should be used for development and debugging only, not in production.

@property (nonatomic, assign) BOOL enableDump;

3.1.1.9 sendKeyboardEvent

Send a keyboard event.

- (BOOL)sendKeyboardEvent:(ASPKeyEvent)event;

3.1.1.10 simulateMouseClick

Simulate a mouse click

// leftButton: YES for the left mouse button, or NO for the right. x, y: The click coordinates.
- (BOOL)simulateMouseClick:(BOOL)leftButton;
- (BOOL)simulateMouseClick:(BOOL)leftButton x:(float)x y:(float)y;

3.1.1.11 setVideoProfileWithWidth

Set the resolution

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

3.1.1.12 setMute

Mutes or unmutes the audio.

@property (nonatomic, assign) BOOL mute;

3.1.2 ASPEngineSDK.h

Connect to Elastic Desktop Service using the specified server connection parameters.

1) Start the streaming service using the server session obtained from PaaS.

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

ASPConnTicket:

2) Start the cloud streaming service with the specified server connection parameters.

This method is typically used for day-to-day debugging in scenarios where you can connect directly to the ASP Server, either by bypassing the gateway or by using a known gateway address with an accessible token.

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

AspConnParam parameters

3.1.2.2 Stop

Disconnect the EDS session

- (int)stop;

3.1.2.3 Pause

Pausing an EDS instance

- (void)pause;

3.1.2.4 Resume

Restore EDS API

- (void)resume;

3.1.2.5 setRenderView

Configure the Elastic Desktop Service view container interface.

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

3.1.2.6 Dispose

Delete the cloud desktop.

- (void)dispose;

3.1.2.7 enableRTC

Use RTC transport

- (void)enableRTC:(bool) enabled;

3.1.2.8 enableVDAagentCheck

Check the VDAagent.

- (void)enableVDAagentCheck:(bool) enabled;

3.1.2.9 enableStatistics

Whether to enable tracking.

- (BOOL)enableStatistics:(BOOL)enabled;

3.1.2.10 dump

The dump interfaces are for development and integration testing only. Do not use them in production, as they are resource-intensive.

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

@property (nonatomic, assign) BOOL enableDump;

3.1.2.11 Delegate

Callbacks

// Handles cloud desktop connection events.
@property (nonatomic, weak) id<ASPEngineDelegate> engineDelegate;
// Handles resolution updates.
@property (nonatomic, weak) id<ASPEngineResolutionUpdateDelegate> resolutionUpdateDelegate;
// Handles cursor events.
@property (nonatomic, weak) id<ASPEngineCursorDelegate> cursorDelegate;
// Handles cloud desktop orientation updates.
@property (nonatomic, weak) id<ASPEngineOrientationUpdateDelegate> orientationUpdateDelegate;
// Handles statistics events.
@property (nonatomic, weak) id<ASPEngineStatisticsDelegate> statisticsDelegate;
// Handles IME events.
@property (nonatomic, weak) id<ASPEngineIMEDelegate> imeDelegate;
// Handles clipboard events.
@property (nonatomic, weak) id<ASPEngineClipboardDelegate> clipboardDelegate;
// Handles gesture events.
@property (nonatomic, weak) id<ASPEngineGestureDelegate> gestureDelegate;
// Handles logging.
@property (class, nonatomic, weak) id<ASPEngineLogDelegate> logDelegate;

3.1.2.12 setVideoProfileWithWidth

Set the EDS resolution

- (void)setVideoProfileWithWidth:(int)width height:(int)height fps:(int)fps; // Target fps for the video stream. This parameter is not yet in use.

3.1.2.13 touch

Dispatches a touch event.

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

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

3.1.2.14 Keyboard

Send keyboard events

- (BOOL)sendKeyboardEvent: (ASPKeyEvent) event;

// Sends the state of the lock keys (Caps Lock, Num Lock, and Scroll Lock).
- (void)sendKeyboardLockModifiers: (int) modifiers;

3.1.2.15 Mouse

Enables or disables mouse mode.

- (BOOL)enableMouseMode:(BOOL)enabled;

Send mouse events

- (void)sendMouseButtonEvent: (ASPMouseButtonEvent)event;

- (void)sendMouseMoveEvent: (ASPMouseMoveEvent)event;

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

3.1.2.16 ime

Send IME-related events

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

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

3.1.2.17 Clipboard

Send clipboard events

- (void)sendClipboardType:(int)type;

The type parameter:

enum ASPEngineClipboardType {
    ASPENGINE_CLIPBOARD_NONE = 0,
    ASPENGINE_CLIPBOARD_UTF8_TEXT,
    ASPENGINE_CLIPBOARD_IMAGE_PNG,  /* All image-supporting clients should support this format. */
    ASPENGINE_CLIPBOARD_IMAGE_BMP,  /* optional */
    ASPENGINE_CLIPBOARD_IMAGE_TIFF, /* optional */
    ASPENGINE_CLIPBOARD_IMAGE_JPG,  /* optional */
};

ASPEngineDelegate

Cloud Computer Connection Callbacks

@protocol ASPEngineDelegate <NSObject>
// An internal engine error occurred.
- (void)onEngineErrorWithErrCode:(int)errCode errMsg:(NSString*)errMsg;
// The connection to the cloud computer succeeded.
- (void)onConnectionSuccess;
// The connection to the cloud computer failed.
- (void)onConnectionFailureWithErrCode:(int)errCode errMsg:(NSString*)errMsg;
// The connection to the cloud computer was lost.
- (void)onDisconnected:(int)reason;
// The first frame from the cloud computer was rendered.
- (void)onFirstFrameRendered:(long)timeCostMS;
// The engine is attempting to reconnect.
- (void)onReconnect;

@end

3.1.2.19 ASPEngineResolutionUpdateDelegate

EDS resolution changed callback.

/**
 * Implement this protocol to receive notifications about video resolution changes.
 */
@protocol ASPEngineResolutionUpdateDelegate <NSObject>

/**
 * Called when the resolution of the video stream changes.
 *
 * @param oldWidth  The previous video width in pixels.
 * @param oldHeight The previous video height in pixels.
 * @param width     The new video width in pixels.
 * @param height    The new video height in pixels.
 */
- (void)onResolutionUpdateWithOldWidth:(int)oldWidth oldHeight:(int)oldHeight
                                 width:(int)width height:(int)height;

@end

3.1.2.20 ASPEngineCursorDelegate

EDS resolution change callback

@protocol ASPEngineCursorDelegate <NSObject>
// Notifies the delegate that the cloud cursor's shape has changed.
- (void)onCursorBitmapUpdateWithHotX:(int)hotX hotY:(int)hotY width:(int)width
height:(int)height rgba:(char*)rgba;
// Notifies the delegate that the cloud cursor has been reset.
- (void)onCursorReset;
// Notifies the delegate that the cloud cursor has been hidden.
- (void)onCursorHide;
// Notifies the delegate that the cloud cursor has moved.
- (void)onCursorMoveWithX:(int)x y:(int)y;
@end

3.1.2.21 ASPEngineOrientationUpdateDelegate

Listen for cloud-side screen rotation events

@protocol ASPEngineOrientationUpdateDelegate <NSObject>

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

@end

3.1.2.22 ASPEngineStatisticsDelegate

Provides reports on performance and key operational status.

@protocol ASPEngineStatisticsDelegate <NSObject>

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

@end

The parameters for ASPStatisticsInfo are:

@interface ASPStatisticsInfo : NSObject

@property (nonatomic, assign) int mReceiveFps; // Client-side received video FPS
@property (nonatomic, assign) int mRenderFps; // Client-side render FPS
@property (nonatomic, assign) double mDownstreamBandwithMBPerSecond; // Downstream bandwidth (MB/s)
@property (nonatomic, assign) double mUpstreamBandwithMBPerSecond; // Upstream bandwidth (MB/s)
@property (nonatomic, assign) long mP2pFullLinkageLatencyMS; // End-to-end latency (ms)
                                           // This value is accurate only when a specific application runs in the guest OS.
@property (nonatomic, assign) long mNetworkLatencyMS; // Network round-trip time (RTT) (ms)
@property (nonatomic, assign) long mPingGatewayRtt;   // Gateway ping RTT (ms)
@property (nonatomic, assign) double mLostRate; // Packet loss rate
@property (nonatomic, assign) long mServerRenderLatencyMS; // Server rendering latency (ms)
@property (nonatomic, assign) long mServerEncoderLatencyMS; // Server encoding latency (ms)
@property (nonatomic, assign) long mServerTotalLatencyMS; // Total server latency (ms)
@property (nonatomic, assign) long accumulateBandwidth; // Cumulative bandwidth
@property (nonatomic, copy  ) NSString *protocolType; // Stream protocol type

@property (nonatomic, copy  ) NSDictionary *infoDic;

@end

3.1.2.23 ASPEngineIMEDelegate

Monitors focus changes in cloud input boxes and tracks the position and status of the input method UI.

/**
 * Defines callbacks for cloud input method events, such as focus changes and UI location updates.
 */
@protocol ASPEngineIMEDelegate <NSObject>

/**
 * Called when a cloud input field gains or loses focus.
 * @param hasFocus `YES` if the input field has focus; otherwise, `NO`.
 */
- (void)onIMEFocusUpdate:(bool)hasFocus;
/**
 * Called when the cloud input method's UI location changes.
 * @param x The new x-coordinate of the UI.
 * @param y The new y-coordinate of the UI.
 */
- (void)onIMELocationUpdateWithX:(int)x y:(int)y;

@end

3.1.2.24 ASPEngineClipboardDelegate

Triggered when the cloud clipboard reads data from or writes data to the client.

@protocol ASPEngineClipboardDelegate <NSObject>

// Called to retrieve data from the client-side clipboard for a paste operation in Elastic Desktop Service (EDS).
- (void)onClipBoardRead:(int)engineId type:(int *)type data:(uint8_t**)data size:(int *) size selection:(uint8_t)selection;
// Called to update the client-side clipboard after a copy operation in Elastic Desktop Service (EDS).
- (void)onClipBoardWrite:(int)engineId type:(int)type data:(uint8_t*)data size:(int)size;

@end

3.1.2.25 ASPEngineGestureDelegate

Provides callbacks for zoom and pan (two-finger gesture).

/**
 * Defines callbacks for two-finger gestures, such as scale and translate.
 */
@protocol ASPEngineGestureDelegate <NSObject>

/**
 * Called when a scale gesture is recognized.
 *
 * @param sx The x-axis scale factor.
 * @param sy The y-axis scale factor.
 */
- (void)onScale:(float)sx sy:(float)sy;

/**
 * Called when a translate gesture is recognized.
 *
 * @param tx The x-axis translation distance.
 * @param ty The y-axis translation distance.
 */
- (void)onTranslate:(float)tx ty:(float)ty;

@end

3.1.2.26 ASPEngineLogDelegate

Log callback

/**
 * A delegate protocol for receiving log messages from the SDK.
 */
@protocol ASPEngineLogDelegate <NSObject>

/**
 * Tells the delegate that a log message is available from the SDK.
 *
 * @param message The log message content.
 * @param tag The tag for categorizing the log message.
 * @param level The severity level of the log message.
 */
- (void)onLogMessage:(NSString *)message tag:(NSString *)tag level:(AspLogLevel)level;

@end

3.1.2.27 Mute

Whether to mute the audio.

/**
 * Sets whether to mute the audio stream.
 *
 * YES: Mutes the audio stream.
 * NO: Does not mute the audio stream. (Default)
 */
@property (nonatomic, assign) BOOL mute;