ASP Android SDK - Cloud Phone - Alibaba Cloud Documentation Center

The Alibaba Cloud Workspace SDK for Android provides an open interface for connecting to cloud computers, cloud apps, and cloud phones. By integrating the SDK, you can quickly customize and build an Android client tailored to your business needs.

1. Quick start

1.1 Get SDK and demo

Download the SDK and demo

Note

By downloading and using the SDK, you agree to the Alibaba Cloud Workspace SDK Privacy Policy.

These documents, SDKs, and clients are for internal use only. Do not distribute them to any third party without permission from Alibaba Cloud.

Environment requirements

Minimum supported Android version: 5.1

AAR package integration

Copy the aspengine-third-release.aar, aspengine-player-release.aar, and wytrace-release.aar to the app/libs directory.
Add the following dependencies to your app module's build.gradle file:

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // The INI configuration parsing library required by aspengine-sdk.
    implementation 'org.ini4j:ini4j:0.5.4'
    // The libraries required by wytrace.
    implementation 'com.squareup.okhttp3:okhttp:5.0.0-alpha.8'
    implementation 'com.google.code.gson:gson:2.10.1'
    implementation 'io.github.aliyun-sls:aliyun-log-android-sdk:2.7.0@aar'
}

Declare the required permissions in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE"/>

Configure the ProGuard keep rules:

-keep class com.aliyun.wuying.aspsdk.** { *; }
-dontwarn com.aliyun.wuying.aspsdk.**

1.2 Integration process

1.3 Best practices

See Best practices for integrating Cloud Phone.

Multiple logon methods are available to get the connection ticket for SDK integration.

For code examples, see the sample code for the lifecycle interfaces.

2. Lifecycle interfaces

2.1 Initialize a StreamView instance

@Override
protected void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
   requestWindowFeature(Window.FEATURE_NO_TITLE);
   getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);
   setContentView(R.layout.activity_stream_view_demo);
   mStreamView = findViewById(R.id.stream_view);
   mStreamView.enableDesktopMode(false);
   mStreamView.scaleStreamVideo(pref.getBoolean("fit_video_content", true) ?
   mStreamView.ScaleType.FIT_STREAM_CONTENT : StreamView.ScaleType.FILL_STREAM_VIEW);
   mStreamView.getASPEngineDelegate().setAlignStreamResolutionWithSurfaceSize(false);
}

<?xml version="1.0" encoding="utf-8"?>
<android.widget.RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".StreamViewDemoActivity">

    <com.aliyun.wuying.aspsdk.aspengine.ui.StreamView
        android:id="@+id/stream_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:focusableInTouchMode="true"
        android:focusable="true"
        android:focusedByDefault="true" />

</android.widget.RelativeLayout>

2.2 Establish a connection

For information about mConfigs values, see Section 4.1.

mStreamView.start(mConfigs);

2.3 Close the connection

mStreamView.stop();

2.4 Destroy a StreamView instance

mStreamView.dispose();
mStreamView = null;

2.5 Multi-StreamView mode

This mode lets you seamlessly switch a single stream between multiple View instances. To implement this mode, follow these steps:

Define and initialize the StreamView instances as described in Section 2.1.

Use IAspEngine to establish a connection. The parameters must be consistent with the Config definition in Section 4.1.

IASPEngine engine = mBuilder.enableRTC(true).build(context);
// Enable data statistics.
engine.enableStatistics(true, true);
ConnectionConfig cc = new ConnectionConfig();
cc.id = CONFIG_DESKTOP_ID;
cc.connectionTicket = CONFIG_CONNECTION_TICKET;
cc.useVPC = CONFIG_USE_VPC;
cc.type = OS_TYPE;
cc.user = CONFIG_USER;
cc.uuid = CONFIG_UUID;

engine.start(cc);

Bind the IAspEngine to a StreamView. This call renders the stream on the specified View.
```
mStreamView.bindASPEngine(engine);
```
Resume rendering on a StreamView. This call directs the View to resume rendering the stream.
```
mStreamView.resumeASPEngine();
```

For more details, see the implementation in the demo application.

2.6 Callbacks

Connection callback proxy: IASPEngineListener

Interface description:

API	Description
onConnectionSuccess(int connectionId)	Triggered when a connection to the cloud phone is successfully established. Returns the connection ID.
onConnectionFailure(int errorCode, String errorMsg)	Triggered if the connection to the cloud phone fails. Returns the error code and error message.
onEngineError(int errorCode, String errorMsg)	Triggered when an internal SDK error occurs. Returns the error code and error message.
onDisconnected(int reason)	Triggered when the connection is disconnected. Returns the integer disconnection reason code.
onReconnect(int errorCode)	Triggered when the SDK attempts to reconnect after a disconnection. Returns the error code that triggered the reconnection.
onFirstFrameRendered(long timeCostMS)	Triggered when the first video frame is rendered. Returns the time elapsed from connection start to first frame, in milliseconds.
onPolicyUpdate(String policy)	Triggered when a policy update is received from the cloud phone. Returns the policy configuration as a string.
onSessionSuccess()	Triggered when the streaming session is successfully established.

Performance data callback proxy: IStatisticsListener

Interface description:

API	Description
onStatisticsInfoUpdate(StatisticsInfo statisticsInfo)	Triggered periodically to provide performance data. Returns a `StatisticsInfo` object containing the latest metrics.

System permission request callback proxy: IRequestSystemPermissionListener

Interface description:

API	Description
bool OnRequestSystemPermission(SystemPermission permission)	Triggered when the SDK needs to request a system permission. The `permission` parameter indicates the type of permission required.

Sample code for registering and unregistering callbacks:

// Listen for connection callbacks.
mStreamView.getASPEngineDelegate().registerASPEngineListener(IASPEngineListener listener);
mStreamView.getASPEngineDelegate().unregisterASPEngineListener(IASPEngineListener listener);
// Listen for performance data callbacks.
mStreamView.getASPEngineDelegate().registerStatisticsListener(IStatisticsListener listener);
mStreamView.getASPEngineDelegate().unregisterStatisticsListener(IStatisticsListener listener);
// Listen for system permission requests.
mStreamView.registerSystemPermissionListener(IRequestSystemPermissionListener listener);
mStreamView.unregisterSystemPermissionListener(IRequestSystemPermissionListener listener);

3. Service API

API	Description
enableVDAgentCheck(boolean enabled)	Specifies whether to enforce a check for VDAgent availability when establishing a connection. This check is enabled by default. If this is set to `true` and the VDAgent is unavailable during connection establishment, an error is reported and the current connection is terminated. Setting this parameter to `false` is not recommended, except for internal debugging purposes.
enableRTC(boolean enabled)	Specifies whether to use RTC to transmit streaming data. RTC is used by default.
enableDesktopMode(boolean enabled)	Enables or disables desktop mode. When enabled, all touch input is converted to mouse events and sent to the server. For cloud phones, we recommend setting this to `false`.
scaleStreamVideo(ScaleType scaleType)	Specifies the scaling behavior for the video stream. For valid values of `ScaleType`, see enum type 5.1 ScaleType.
setVideoProfile(int width, int height, int fps, IRemoteResult result)	Sets the resolution for the video stream. The `fps` (frame rate) parameter is not currently supported.
boolean sendKeyEvent(KeyEvent event) and sendKeyboardEvent(KeyEvent event, IRemoteResult result)	Sends keyboard events to the remote session.
boolean simulateMouseClick(boolean leftButton)	Simulates a mouse click in the remote session. Set the parameter to `true` for a left-click or `false` for a right-click.
boolean enableMouseMode(boolean enabled)	Enables or disables mouse mode.
boolean sendMouseEvent(MotionEvent motionEvent) and sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)	Sends mouse events to the remote session.
reconnect(String connectionToken)	Reconnects to the session after an unexpected disconnection. This method is typically used to handle a disconnection with `reason=2200`. To reconnect, your application must call the OpenAPI to get a new connection token for the cloud phone and then pass it to this method.
boolean setMediaStreamPlayer(MediaStreamPlayer player)	Replaces the SDK's default media engine with a custom engine provided by your application. This method must be called before initiating streaming or after the stream is disconnected.
void setAlignStreamResolutionWithSurfaceSize(boolean aligned)	Enables or disables automatically aligning the stream resolution with the client-side `SurfaceView` size when streaming starts. This feature is enabled by default. For cloud phones, we recommend disabling this feature.
void mute(boolean muted)	Enables or disables mute mode.
void enableStatistics(boolean enabled)	Enables or disables the collection of performance data.
mStreamView.getASPEngineDelegate().requestIFrame()	Requests a keyframe.
Under `mStreamView.getASPEngineDelegate()`: registerFileTransferListener(IFileTransferListener var1) and unregisterFileTransferListener(IFileTransferListener var1) and mStreamView.getASPEngineDelegate().uploadFiles(pathList, "/sdcard/Download/");	Manages file upload and download. For implementation details, see the demo application.
Under `mStreamView.getASPEngineDelegate()`: addDataChannel(DataChannel var1) and removeDataChannel(DataChannel var1)	Adds or removes a custom data channel to exchange data with the remote session. For implementation details, see the demo application.
Under `mStreamView.getASPEngineDelegate()`: addLyncChannel(LyncChannel var1) and removeLyncChannel(LyncChannel var1)	Adds or removes the channel for sending ADB commands. For implementation details, see `AspAdbUtil` in the demo application.
void setToQualityFirst()	Sets quality-first mode. This mode supports a maximum frame rate of 30 fps and the image quality is set to High. Not supported on cloud phones.
void setToFpsFirst()	Sets smoothness-first mode. This mode supports a maximum frame rate of 60 fps and the image quality is set to Good. Not supported on cloud phones.
void setToCustomPicture(int fps, int quality);	Sets a custom mode that allows you to define the frame rate and image quality. The `fps` parameter accepts values from 0 to 60. A higher value results in smoother video. The `quality` parameter accepts values from 0 to 4, where `0` is lossless, `1` is high, `2` is good, `3` is fair, and `4` is auto. Not supported on cloud phones.
Under `mStreamView.getASPEngineDelegate()`: registerIMEListener, unregisterIMEListener, setImeType, enableRelativeMouse, etc.	Not supported on cloud phones.

4. Parameters

4.1 Config

Use these parameters to establish a connection.

Parameter	Type	Description
`StreamView.CONFIG_DESKTOP_ID`	string	The instance ID. This value corresponds to the `ResourceId` returned by the `DescribeUserResources` API.
`StreamView.CONFIG_CONNECTION_TICKET`	string	The connection authentication ticket. Obtain this ticket by calling the `GetConnectionTicket` API.
`StreamView.CONFIG_PREFER_RTC_TRANSPORT`	boolean	Enables the RTC channel when set to `true`. This setting is recommended for a cloud phone.
`StreamView.CONFIG_ENABLE_VDAGENT_CHECK`	boolean	Enables a VDAgent availability check during connection when set to `true`. This setting is recommended for a cloud phone.
`StreamView.CONFIG_ENABLE_STATISTICS`	boolean	Set to `true` to enable performance statistics, which are then displayed as an overlay on the video stream. This setting is recommended for a cloud phone.
`OSType`	string	The operating system type. Must be set to `android` for a cloud phone.

4.2 StatisticsInfo

Performance data

API	Type	Description
mReceiveFps	int	Received frame rate
mRenderFps	int	Rendered frame rate
mDownstreamBandwithMBPerSecond	double	Downstream bandwidth
mUpstreamBandwithMBPerSecond	double	Upstream bandwidth
mP2pFullLinkageLatencyMS	long	End-to-end latency (deprecated)
mNetworkLatencyMS	long	Network RTT
mPingGatewayRttMS	long	Ping RTT
mLostRate	double	Packet loss rate
mServerRenderLatencyMS	long	Cloud-side rendering latency
mServerEncoderLatencyMS	long	Cloud-side encoding latency
mServerTotalLatencyMS	long	Cloud-side total latency
mTotalDownstreamBandwidth	long	Total downstream bandwidth
mGuestCpuUsage	long	Guest CPU usage
mStreamType	String	Streaming protocol

5. Enumeration types

5.1 ScaleType

Specifies how the streamed image is scaled to fit the StreamView.

Parameter	Description
FILL_STREAM_VIEW	Stretches the streamed image to fill the entire StreamView. This setting does not preserve the image's original aspect ratio, which can distort the image if the aspect ratios do not match.
FIT_STREAM_CONTENT	Scales the streamed image to fit inside the StreamView while maintaining its original aspect ratio. This prevents distortion but may leave empty areas if the image and view aspect ratios differ.

5.1 SystemPermission

Specifies the system permissions.

Parameter	Description
RECORDAUDIO	Allows recording audio.

6. Customizing MediaStreamPlayer

Note

A custom multimedia implementation is not required, as the SDK provides a default one.

6.1 Process media data

Implementing com.aliyun.wuying.aspsdk.aspengine.MediaStreamPlayer allows an application to use a custom media engine to process streaming media data, which consists mainly of the following:

Video stream data: A raw video stream primarily composed of H.264/H.265 compressed frames.
Adaptive image stream: An image stream consisting mainly of bitmaps.
Audio downstream data: An audio stream primarily in Opus/PCM format.
Cursor data: When virtual mouse mode is enabled, the application receives cursor image and position data, allowing it to independently render a virtual cursor.

An application can call IASPEngine.setMediaStreamPlayer to set a custom media engine implementation for the Alibaba Cloud Workspace SDK.

6.2 MediaStreamPlayer

MediaStreamPlayer is an abstract class that requires applications to implement global initialization and cleanup methods, and to provide a custom implementation for handling different media data types:

Where:

The IVideoStreamHandler interface is for handling video stream data.
The IAdaptiveGraphicStreamHandler interface is for handling adaptive graphic stream data.
The IAudioPlaybackStreamHandler interface is for handling audio playback data.
The ICursorBitmap interface is for handling cursor data.

An application can implement one or more of the preceding interfaces. The Alibaba Cloud Workspace SDK then determines the cloud streaming type based on which interfaces are implemented, as follows:

If the app implements both IVideoStreamHandler and IAdaptiveGraphicStreamHandler, the streaming mode is set to Mixed. In this mode, Alibaba Cloud Workspace automatically switches between the adaptive graphic stream and the video stream.
If the app only implements IVideoStreamHandler, the streaming mode is set to Video stream only, and the server will only provide a video stream.
If the app only implements IAdaptiveGraphicStreamHandler, the streaming mode is set to Image stream only, and the server will only provide an image stream.

To customize how the SDK handles different types of media data, implement the onCreateXXXHandler methods in MediaStreamPlayer:

    @Override
    protected IVideoStreamHandler onCreateVideoStreamHandler() {
        return new VideoStreamHandler();
    }

    @Override
    protected IAdaptiveGraphicStreamHandler onCreateAdaptiveGraphicStreamHandler() {
        return null;
    }

    @Override
    protected IAudioPlaybackStreamHandler onCreateAudioPlaybackStreamHandler() {
        return new AudioPlaybackStreamHandler();
    }

    @Override
    protected ICursorBitmapHandler onCreateCursorBitmapHandler() {
        return null;
    }

In the example above, the custom media engine implements both IVideoStreamHandler and IAudioPlaybackStreamHandler. The onCreateXXXHandler method runs only once per streaming session.

Calling the main method:

6.2.1 initialize

Your application implements this method to globally initialize the custom media engine.

The system calls this method once during each streaming process.

public ErrorCode initialize()

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.2.2 release

Releases all global resources associated with the custom media engine.

This method is called once during each streaming session.

public ErrorCode release()

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.2.3 enableStatistics

Use this method to enable or disable performance statistics collection.

public void enableStatistics(boolean enabled)

Parameters

Parameter

Type

Description

enabled

boolean

true

false

6.2.4 onCreateVideoStreamHandler

Provides a media engine implementation for handling video stream data.

The SDK executes this method once per stream.

public IVideoStreamHandler onCreateVideoStreamHandler()

Return value

Type

Description

IVideoStreamHandler

The media engine implementation that the application provides to handle video stream data.

Return null if the application does not provide an implementation. In this case, the SDK discards the video stream data.

6.2.5 onCreateAdaptiveGraphicStreamHandler

Provides a media engine implementation for handling adaptive graphic stream data.

The SDK calls this method once per streaming session.

public IAdaptiveGraphicStreamHandler onCreateAdaptiveGraphicStreamHandler()

Return value

Type

Description

IAdaptiveGraphicStreamHandler

Your app's media engine implementation for handling adaptive graphic stream data.

If your app does not provide an implementation, return null. In this case, the SDK does not process the graphic stream data.

6.2.6 onCreateAudioPlaybackStreamHandler

Provides a media engine implementation for processing audio downstream data.

The SDK calls this method once per streaming session.

public IAudioPlaybackStreamHandler onCreateAudioPlaybackStreamHandler()

Return value

Type

Description

IAudioPlaybackStreamHandler

A media engine implementation provided by the application that processes audio downstream data.

If the application provides no implementation, return null. In this case, the SDK does not process the audio downstream data.

6.2.7 onCreateCursorBitmapHandler

Provides the SDK with a media engine for cursor data processing.

The SDK calls this method once per streaming session.

The SDK uses the returned interface implementation only in virtual mouse mode.

public ICursorBitmapHandler onCreateCursorBitmapHandler()

Return value

Type

Description

ICursorBitmapHandler

The media engine implementation for cursor data processing.

Return null if your app does not implement cursor data processing. In this case, the SDK does not process cursor data, even in virtual mouse mode.

6.3 IVideoStreamHandler

This interface provides the primary methods for handling video streams. The main workflow is as follows:

When the app switches between the foreground and background, the Surface used for rendering is destroyed or recreated. In this case, the IVideoStreamHandler.setVideoSurface method is called repeatedly. When the Surface is destroyed, the surface object passed to setVideoSurface is null. Your app must handle faults in the decoder and the renderer.

By implementing the IVideoStreamHandler.setEventHandler method, an application obtains the event handling interface provided by the Alibaba Cloud Workspace SDK. The application uses this interface to notify the SDK of video processing events from its custom media engine, primarily for collecting performance data.

    @Override
    public void setEventHandler(EventHandler handler) {
        Log.i(TAG, "setEventHandler handler " + handler);
        VideoStreamEventHandler.getInstance().reset(handler);
    }

...
    
    public synchronized void onVideoFrameRendered() {
        VFrame frame = mVideoFrame.remove();
        if (mEnabled && mHandler != null) {
            Event event = new Event();
            event.type = EventType.RENDER_PERF_INFO;
            event.decodePerfInfo = new VDecodePerfInfo();
            event.renderPerfInfo = new VRenderPerfInfo();
            event.renderPerfInfo.frameId = frame.frameId;
            event.renderPerfInfo.sessionId = frame.sessionId;
            // Notifies the Wuying SDK that a video frame has been rendered. The SDK then uses the frameId to calculate the client-side end-to-end latency.
            mHandler.callback(event);
        }
    }

6.3.1 setEventHandler

Called when the SDK loads the custom media engine. Provides an EventHandler for sending video stream processing events.

public void setEventHandler(EventHandler handler)

Parameters

Parameter

Type

Description

handler

EventHandler

An object provided by the Alibaba Cloud Workspace SDK that your app uses to send video stream processing events to the SDK.

6.3.2 addVideoTrack

Called when a video stream is created.

Currently, only one video stream can exist in a single streaming session.

ErrorCode addVideoTrack(int trackId, VProfile profile);

Parameters

Parameter

Type

Description

trackId

int

The ID of the video stream.

profile

VProfile

Information about the video stream.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.3.3 setVideoSurface

Called when the video rendering Surface changes state.

ErrorCode setVideoSurface(int trackId, Surface surface);

Parameters

Parameter

Type

Description

trackId

int

The ID of the video stream.

surface

android.view.Surface

The rendering Surface object.

This value can be null when the app enters the background or the device is locked.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.3.4 playVideo

Your application must implement this method. The SDK calls it when a video stream is ready for playback.

ErrorCode playVideo(int trackId);

Parameters

Parameter

Type

Description

trackId

int

The video stream ID.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.3.5 removeVideoTrack

Removes the specified video stream.

ErrorCode removeVideoTrack(int trackId);

Parameters

Parameter

Type

Description

trackId

int

The ID of the video stream.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.3.6 pushVideoFrame

You implement this method in your application. The SDK calls this method when it receives a new video frame.

ErrorCode pushVideoFrame(int trackId, VFrame frame);

Parameters

Parameter

Type

Description

trackId

int

The ID of the video stream.

frame

VFrame

The received video frame.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.3.7 getVideoTracks

Returns information about all video streams currently being processed.

HashMap<Integer, VProfile> getVideoTracks();

Return value

Type

Description

HashMap<Integer, VProfile>

A HashMap containing information about all video streams being processed.

6.3.8 release

This method is implemented by the application. It is called when all video streams are destroyed, allowing the application to perform cleanup.

ErrorCode release();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4 IAudioPlaybackStreamHandler

This interface provides methods for handling audio stream data. The workflow is as follows:

6.4.1 initAudio

Called when an audio channel is created.

ErrorCode initAudio();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.2 deInitAudio

Called when an audio channel is destroyed.

ErrorCode deInitAudio();

Returns

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.3 startAudioPlayback

Called before the cloud phone begins sending the audio stream.

ErrorCode startAudioPlayback();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.4 stopAudioPlayback

Your application implements this method. The SDK calls this method when the cloud phone stops sending the audio stream.

ErrorCode stopAudioPlayback();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.5 pushAudioPlaybackFrame

Your application implements this method. The SDK calls this method when a new downstream audio frame is received.

ErrorCode pushAudioPlaybackFrame(AFrame pbData);

Parameters

Parameter

Type

Description

pbData

AFrame

The received downstream audio frame.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.6 updateAudioPlaybackVol

Called when the system volume of the cloud phone changes.

ErrorCode updateAudioPlaybackVol(int volume);

Parameters

Parameter

Type

Description

volume

int

The value ranges from 0 (muted) to USHRT_MAX.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.7 updateAudioPlaybackMute

Called when the cloud phone is muted or unmuted.

ErrorCode updateAudioPlaybackMute(int mute);

Parameters

Parameter

Type

Description

mute

int

Indicates the mute status. A value of 1 means the cloud phone is muted, and 0 means it is unmuted.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.4.8 release

This method is implemented by the application. It is called when an audio channel is destroyed to allow the application to perform cleanup.

ErrorCode release();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.5 IAdaptiveGraphicStreamHandler

This interface provides methods for processing image stream data. The workflow is as follows:

The application receives image frames as ARGB8888 bitmaps.

Each streaming session supports a maximum of one image stream.

6.5.1 setAdaptiveGraphicSurface

Called when the state of the Surface used for image rendering changes.

ErrorCode setAdaptiveGraphicSurface(Surface surface);

Parameters

Parameter

Type

Description

surface

android.view.Surface

The Surface for image rendering.

This object can be null when the app enters the background or the screen locks.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.5.2 invalidateAdaptiveGraphicSurface

Called when new adaptive graphic frame data is available.

ErrorCode invalidateAdaptiveGraphicSurface(Region region, byte[] buffer, BitmapFormat format);

Parameters

Parameter

Type

Description

region

Region

The drawing area for the adaptive graphic frame.

buffer

byte[]

The adaptive graphic frame data.

format

BitmapFormat

The format of the adaptive graphic frame. The default is ARGB8888.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.5.3 release

Called when the image stream is destroyed to perform cleanup.

ErrorCode release();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.6 ICursorBitmapHandler

This interface defines the primary methods for handling cursor data. To render the cursor image in virtual mouse mode, the application must provide the SDK with an implementation of this interface. The main workflow is as follows:

6.6.1 setCursorBitmap

Called when the cursor graphic on the cloud phone changes.

ErrorCode setCursorBitmap(CursorBitmap bitmap);

Parameters

Parameter

Type

Description

bitmap

CursorBitmap

The cursor graphic data from the cloud phone.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.6.2 unsetCursorBitmap

Called when the cursor on the cloud phone is hidden.

ErrorCode unsetCursorBitmap();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.6.3 setCursorPosition

Sets the cursor position in the cloud phone.

ErrorCode setCursorPosition(float x, float y);

Parameters

Parameter

Type

Description

float

The x-coordinate of the cursor.

float

The y-coordinate of the cursor.

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

6.6.4 release

Called after the connection disconnects and the cursor disappears to perform cleanup.

ErrorCode release();

Return value

Type

Description

ErrorCode

ErrorCode.OK on success, or an error code on failure.

Error codes

Error code	Error message (`%s` represents a cloud phone or cloud app)	Module	Cause
Error codes 2–26 are primarily related to network issues.
2	Failed to connect to %s.	ASP SDK	Invalid MAGIC value.
3	Failed to connect to %s.	ASP SDK	Invalid data.
4	The client and server versions do not match.	ASP SDK	Version mismatch.
5	A TLS connection is required.	ASP SDK	The server requires a TLS connection, but the client did not initiate one.
6	Unexpected TLS connection.	ASP SDK	The connection does not require TLS, but it was used.
7	Permission denied to connect to %s.	ASP SDK	Insufficient permissions.
8	Invalid client ID during migration.	ASP SDK	Invalid client ID during migration.
9	Failed to connect to %s.	ASP SDK	The channel does not exist.
20	Failed to connect to the ASP server.	ASP SDK	Channel connection error.
21	A TLS authentication error occurred.	ASP SDK	TLS authentication error.
22	Failed to connect to %s.	ASP SDK	Channel link error.
23	Failed to connect to %s.	ASP SDK	Connection authentication error.
24	Failed to connect to %s.	ASP SDK	Connection I/O error.
25	Failed to connect to %s.	ASP SDK	Ticket validation failed. This error also occurs when reusing a ticket from a terminated session.
26	xquic handshake failed.	ASP SDK	xquic handshake failed.
1206	The ticket is already in use.	ASP SDK	A ticket can be reused, but only for one connection at a time. This error occurs if you attempt to establish a new connection while the cloud phone is already in use.
1207	Ticket invalidated by instance restart.	ASP SDK	The instance was restarted, which invalidated the ticket.
SDK error codes for collaborative mode
1000	Token is empty.	ASP SDK	These errors occur only in collaborative mode when the secondary validation between the client and the server fails.
1001	User is empty.	ASP SDK
1200	Token is invalid.	ASP SDK
1201	VM is invalid.	ASP SDK
1202	An admin internal error occurred.	ASP SDK
1203	User is invalid.	ASP SDK
1204	The token has expired.	ASP SDK
1500	A server internal error occurred.	ASP SDK
1501	A server network error occurred.	ASP SDK
Connection interruptions and other errors
2000	Disconnected from the server because fetching data from %s timed out.	ASP SDK	Data fetch timeout.
2001	%s disconnected from the server, possibly because its process was terminated.	ASP SDK	This typically occurs when the process on the client-side is terminated. For example, an Android app is closed by the user pressing the Home button.
2002	Another user has connected to the current %s from a different terminal.	ASP SDK	The session was taken over by another user in preemptive mode.
2003	%s is shutting down or restarting. This is usually an administrator-initiated action.	ASP SDK	The cloud phone was shut down or restarted, typically by an administrator.
2004	The current user connection was terminated.	ASP SDK	The client initiated the disconnection, or the server triggered a kick or disconnect action.
2005	Session disconnected: usage time limit reached.	ASP SDK	The session was terminated because it reached the usage duration limit set by the administrator.
2006	Your permission to use this cloud phone has been revoked by the administrator. You will be logged out and disconnected.	ASP SDK	The user's authorization was revoked by an administrator.
2010	Failed to connect to %s.	ASP SDK	Failed to connect to Vdagent.
2011	An error occurred while passing connection parameters.	ASP SDK	An invalid parameter was passed when connecting to the server.
2027	The stream pull mode was switched.	ASP SDK	The stream pull mode was switched from preemptive mode to collaborative mode, or from collaborative mode to preemptive mode.
2100	Clipboard permission denied to copy from %s to the local device.	ASP SDK	Clipboard access from the remote instance to the local client is denied by policy.
2101	Clipboard permission denied to copy from the local device to %s.	ASP SDK	Clipboard access from the local client to the remote instance is denied by policy.
2200	%s is attempting to reconnect...	ASP SDK	The connection was lost due to a network issue, and the ASP SDK is attempting to reconnect.
2201	Your device encountered a network anomaly, causing %s to disconnect.	ASP SDK	The connection was lost due to a network issue. The ASP SDK does not support reconnection due to image constraints; the app-side must initiate the reconnection.
2202	Reconnection to %s timed out.	ASP SDK	The ASP SDK reconnection attempt timed out.
2210	Connection lost while the client device was asleep.	ASP SDK	The local network was disconnected while the client device was asleep, which caused the cloud phone connection to be lost.
2212	Connection lost due to a local network anomaly.	ASP SDK	A local network anomaly was detected, which caused the cloud phone to disconnect.
2220	Connection lost due to a local network anomaly.	ASP SDK	A local network anomaly was detected, which caused the cloud phone to disconnect.
2240	Reconnection failed because the token in the ticket is invalid.	ASP SDK
2300	Connection failed due to an invalid parameter from the app-side.	app-side
2501	The client failed to connect to the stream gateway. The network is unreachable.	stream gateway
2502	The client failed to connect to the stream gateway. The TCP connection to the stream gateway IP address timed out after three attempts (15 seconds total).	stream gateway
2503	The client failed to connect to the stream gateway due to an unknown network error.	stream gateway
2504	The client failed to connect to the stream gateway. The connection was aborted by software.	stream gateway
2505	The client failed to connect to the stream gateway. The connection was refused.	stream gateway
2506	The ticket is invalid. The gateway failed to parse the token.	stream gateway
2507	The ticket is invalid because it has expired.	stream gateway
2508	The ticket is invalid due to a UUID mismatch.	stream gateway
2509	The stream gateway failed to probe the ASP server.	stream gateway
2510	The probe to the server was rejected. Resolution: Ensure that the server is listening on port 5912.	stream gateway
2511	The probe to the server failed due to an error other than a timeout or refusal.	stream gateway
2512	The stream gateway token validation failed. The VPC ID in the management token does not match the VPC ID of the stream gateway.	stream gateway
2513	The TCP connection was reset during the "SayHello" handshake between the client and the stream gateway.	stream gateway
2520	The client connection failed; a self-diagnostic check indicates a network anomaly.	ASP SDK
2521	The client was disconnected after three failed reconnection attempts during the TLS handshake phase with the stream gateway.	ASP SDK
2522	A connection error occurred in a VPN environment.	ASP SDK
2523	The client is attempting to connect by using the GM/T protocol suite. Verify the server configuration or select a compatible connection method.	ASP SDK
2701	A client-side network issue occurred.	ASP SDK
2702	The SSL handshake between the client and the stream gateway timed out.	ASP SDK
2703	The "SayHello" handshake between the client and the stream gateway timed out.	ASP SDK
2704	The ASP server response to the connection establishment request timed out. Possible causes: The ASP server is unresponsive, network anomaly, frozen instance, or high memory/CPU usage.	ASP SDK
2705	The ASP client timed out while waiting for the first frame. Possible causes: The ASP server is unresponsive, no frames are being generated due to a screen capture or GPU driver issue, a network anomaly, or high memory/CPU usage.	ASP SDK
2706	High local CPU or memory usage on the client may cause connection failures.	ASP SDK
2707	The ASP server timed out while retrieving the first screen capture frame from the guest OS.	ASP SDK
2708	Connection failed because an SDK thread is stuck.	ASP SDK
Client-side logic errors
5100	The connection from %s to the ASP server timed out.	app-side	The client-side did not receive a "connected" event within the specified time period.
5102	Fetching data from %s timed out.	app-side	The client-side received a "connected" event but did not receive a "display" event within the specified time period.
5004	Invalid startup parameters.	app-side	Invalid startup parameters were passed to the client-side. This typically occurs during development.
5200	Client reconnection timed out.	app-side

8. FAQ

Restart a cloud phone

To restart a cloud phone, call the RebootAndroidInstancesInGroup API. This action temporarily disconnects the client from the cloud phone. After the restart is complete, you will need to reconnect from the client.

Public maven

Public Maven hosting is not currently supported. To integrate the SDK, you can upload the AAR library to your own Maven repository.

Common ADB commands

Feature	Command
Back button	input keyevent KEYCODE_BACK
Home button	input keyevent KEYCODE_HOME
App switch	input keyevent KEYCODE_APP_SWITCH
Mute	input keyevent 164
Volume up	input keyevent KEYCODE_VOLUME_UP
Volume down	input keyevent KEYCODE_VOLUME_DOWN
Hide navigation bar	setprop persist.wy.hasnavibar false; killall com.android.systemui
Show navigation bar	setprop persist.wy.hasnavibar true; killall com.android.systemui
Screenshot	screencap -p /sdcard/Download/abc.png