文档中心

云游戏Android SDK文档v1.6.2

云游戏Android SDK 主要功能是为APP赋予游戏试玩能力，用户在运营平台配置好了试玩游戏后，客户端App通过SDK进行试玩操作，提升游戏分发转化率。

简介

云游戏Android SDK 发行版包括aar包、javadoc文档、完整的Demo示例。以下使用表示SDK解压根目录。

• AAR文件：/aar,开发时导入
• mapping：/mapping，mapping文件
• javadoc文档：/javadoc，javadoc文档
• 示例项目源码：/demoSrc，完整的demo目录。帮助您快速熟悉开发SDK
• 示例项目APK：/demo.apk，demo apk
• 用户手册：本文档

云游戏 SDK 下载

运行环境

可运行于 Android 4.2( API Level 16) 及 以 上 版 本 。

SDK导入及配置

申请密钥对(ak和sk)

开发者请向运营申请创建App并获取sdk使用的ak和sk。

导入aar包

SDK包含gameboxlib-veriosn-xxx.aar，请将aar文件复制到项目libs目录，并根据如下代码配置build.gradle

android {
   //android标签内添加aar目录
    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

dependencies {
	//添加依赖
	compile fileTree(dir: 'libs', include: ['*.jar'])
    compile(name: 'gameboxlib-veriosn-xxx', ext: 'aar')
}

SDK权限配置

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

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

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

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

android:name="android.permission.ACCESS_WIFI_STATE" />

代码混淆

-keepattributes SourceFile,LineNumberTable,Signature -keepclasseswithmembernames class 

* { native <methods>; } -keep class com.alibaba.fastjson.** { *; } -keep class com.mci.** 

{ *; }

SDK初始化

在Application的onCreate方法中调用如下代码完成初始化：

/**
     * 初始化sdk
     *
     * @param ak appKey
     * @param sk secKey
     */ public void init(String ak, String sk, String dc);

游戏获取

游戏列表获取，游戏列表支持分页获取。

同步方法，在非UI线程中调用。

List<GameInfo> gameList = GameBoxManager.getInstance(this).queryGameList(int start,int limit)

根据gid获取运营平台配置的游戏 。 (added v1.2.0)

同步方法，在非UI线程中调用。

GameInfo gidGameInfo = GameBoxManager.getInstance(this).queryGame(int gid)

根据包名获取运营平台配置的游戏列表。 (added v1.2.0)

同步方法，在非UI线程中调用。

List<GameInfo> pkgGameList = GameBoxManager.getInstance(this).queryGames(String pkg)

根据游戏名称获取运营平台配置的游戏列表。 (added v1.5.4)

同步方法，在非UI线程中调用。

List<GameInfo> pkgGameList = GameBoxManager.getInstance(this).queryNameGames(String appName)

更新单个游戏信息

同步方法，在非UI线程中调用。

GameInfo gameInfo = GameBoxManager.getInstance(this).updateGameInfo(GameInfo info)

游戏试玩

申请试玩设备

试玩某一款游戏时传入试玩游戏信息，使用sdk申请设备。

如申请设备成功则返回状态码：APIConstants.API_CALL_SUCCESS和DeviceControl用于控制设备，否则返回对应错误码。

GameBoxManager.getInstance(this).applyCloudDevice(@NonNull GameInfo gameInfo, @NonNull new

 APICallback<DeviceControl>(){ @Override public void onAPICallback(DeviceControl deviceControl, int code)

 { //回调 } })

如需执行脚本文件传入scriptMap,没有可以不传

scriptMap值说明

如需指定标签分组tagKey,没有可以不传

GameBoxManager.getInstance(this).applyCloudDevice(@NonNull GameInfo gameInfo, boolean playQueue,String tagKey,

 HashMap<String,String> scriptMap, @NonNull new APICallback<DeviceControl>(){ @Override public void 

onAPICallback(DeviceControl deviceControl, int code) { //回调 } })

启动游戏试玩

在设备申请成功后，可使用返回的DeviceControl启动游戏试玩。游戏试玩界面需要添加到一个FragmentActivity中，

需要传入ViewGroup的id供添加试玩View。如返回状态码：APIConstants.CONNECT_DEVICE_SUCCESS则表示设备启动成功。

建议试玩界面全屏展示，参照demo中试玩界面

DeviceControl.startGame(@NonNull FragmentActivity activity, @IdRes int containerId, @NonNull APICallback<String> callback)

试玩设置

设置试玩监听

/**
 * 设置试玩监听
 * @param listener    PlayListener 回调
 */ public abstract void setPlayListener(PlayListener listener); /**
 * 试玩监听
 */ public interface PlayListener { /**
     * 网络延时反馈
     *
     * @param ping 网络延时，单位ms
     */ void onPingUpdate(int ping); /**
         * 无操作超时回调
         *
         * @param type    类型。1为后台，2为前台
         * @param timeout 超时时长，单位s
         * @return 返回true表示消耗了事件，sdk不处理超时逻辑；返回false表示未消耗事件，在倒计时结束后，sdk会停止试玩
         */ boolean onNoOpsTimeout(int type, long timeout); /**
         * 设备信息返回
         *
         * @param info 统计信息json format
         */ void onPlayInfo(String info){ "downRate":%d, //总下行流量 "upRate":%d, //总上行流量 "videoFps":%d, //

实时视频帧率 "videoBitrate":%d, //视频码率 "rtt":%d, //RTT "screenFps":%d, //刷新率 "captureTimeAvg":%d,

 //平均采集耗时 "captureTimeMax":%d, //最大采集耗时 "captureTimeMin":%d, //最小采集耗时 "videoEncodingTimeAvg":%d,

 //平均编码耗时 "videoEncodingTimeMax":%d, //最大编码耗时 "videoEncodingTimeMin":%d, //最小编码耗时 "packetLoss":%.2f,

 //丢包率 "decodeTimeAvg":%d, //平均解码耗时 "decodeTimeMax":%d, //最大解码耗时 "decodeTimeMin":%d, //最小解码耗时

 "videoRendererFps":%d //渲染帧率 }

设置试玩结束监听，支持试玩结束倒计时

/**
     * 设置试玩倒计时监听
     * @param threshold 阈值，到达开始倒计时回调，如果小于等于0，则从设置监听起开始回调
     * @param listener 监听listener
     */ public abstract void setTimeCountDownListener(int threshold, TimeCountDownListener listener); /**
 * 试玩结束倒计时监听
 */ public interface TimeCountDownListener { /**
     * 倒计时触发
     *
     * @param remainingTime 剩余时间，单位s秒
     */ void countDown(int remainingTime); }

设置前后台无操作超时

/**
 * 设置无操作超时  (modified v1.5.3)
 * @param foregroundTimeout 前台超时，单位s
 * @param backgroundTimeout 后台超时，单位s
 */ public abstract void setNoOpsTimeout(long foregroundTimeout, long backgroundTimeout);

设置试玩清晰度，更高的清晰度试玩效果更佳，但是相对消耗流量也更多。分辨率码率由智能云平台-->应控用部署-->配置管理设置

/**
     * 调整试玩的码率
     * @param level 等级，目前支持5档
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_AUTO} 自动
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_HD} 高清switchQuality
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_ORDINARY} 普通
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_HS} 一般
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_LS} 流畅
     */ public abstract void switchQuality(@APIConstants.VideoQuality String level);

设置游戏分辨率(added 1.6.2)设置优先级大于智能云平台设置

/**
    * 设置游戏分辨率,支持四档,从高档到低档
    * @param infos
    */ public abstract void setVideoLevels(List<GameQualityInfo> infos);

GameQualityInfo字段如下:

动态设置游戏分辨率(added 1.6.2)

/**
 * 动态设置分辨率 设置后马上生效
 * @param info
 */ public abstract void setVideoLevel(GameQualityInfo info);

获取默认分辨率,没有默认返回""(added v1.5.4)

/**
     * 
     * 
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_AUTO} 自动
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_HD} 高清switchQuality
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_ORDINARY} 普通
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_HS} 一般
     * {@link APIConstants#DEVICE_VIDEO_QUALITY_LS} 流畅
     */ public abstract @APIConstants.VideoQuality String getDefaultGameLevel();

设置视频流是否强制竖屏(added v1.5.4)

/**
     * 
     * 设置视频流显示模式，默认自动切换，需要在startGame之前调用
     */ public abstract void setVideoOrientation(int orientation);

设置声音开关

/**
     * 试玩声音开关
     * @param audioSwitch
     */ public abstract void setAudioSwitch(boolean audioSwitch);

设置云手机声音大小(added 1.6.2)

/**
     * 发送按键事件
     * @param keyCode 使用红手指的{@link com.mci.play.MCIKeyEvent}里面的code
     *                MCIKeyEvent.KEYCOED_VOLUME_UP    音量增加
     *                MCIKeyEvent.KEYCOED_VOLUME_DOWN  音量减少
     */ public abstract void sendKeyEvent(int keyCode);

resume和pause方法用于app切换前后台(added 1.6.2)

/**
  * 切回到前台调用,会继续解析音视频,流会继续推送.
  */ public abstract void resume(); /**
  * 切到后台调用,会停止解析音视频,流会继续推送
  */ public abstract void pause();

退出试玩

在退出试玩时调用，否则无法进行下一次试玩，建议在Activity onDestory中调用

/**
     * 停止试玩，在退出试玩的时候必须回调，否则无法进行下一次试玩
     */ public abstract void stopGame();

如需停止游戏后执行脚本,stopGame可以传入HashMap scriptMap

scriptMap值说明

/**
     * 停止试玩，在退出试玩的时候必须回调，否则无法进行下一次试玩
     */ public abstract void stopGame(HashMap<String,Object> scriptMap);

### 排队机制

排队机制是在原有设备申请接口上新增的机制，在设备使用高峰期可以帮助产品挽留用户。排队过程中只能同时一款游戏进行排队，

排队过程中可以申请进入其他有空闲设备的机器。

#### 设置会员等级

会员等级分为普通会员`MemberLevel.NORMAL`、VIP会员`MemberLevel.VIP`、超级VIP会员`MemberLevel.SUPER_VIP`，

默认为普通会员。开发者可以与自己的会员体系进行映射，会议会影响加速效果，在加速之前可通过`GameBoxManager`

先进行全局的会员等级设置。

```java
   /**
     * 设置会员等级
     *
     * @param memberLevel
     */逻辑
    public void setMemberLevel(MemberLevel memberLevel) {
        mMemberLevel = memberLevel;
    }

    /**
     * 获取当前会员等级
     *
     * @return
     */
    public MemberLevel getMemberLevel() {
        return mMemberLevel;
    }

申请排队

申请设备时playQueue为true在设备不足的情况下会进入排队状态，返回状态码APIConstants.WAITING_QUEUE，此时无法调用DeviceControl.startGame()。

同一时间只能有一款游戏进行排队，如在排队过程中有其他游戏进入队列则返回APIConstants.ERROR_OTHER_DEVICE_WAITING

/**
     * 根据游戏信息申请试玩设备
     *
     * @param gameInfo  游戏信息
     * @param playQueue 如果没有设备是否自动进入队列
     * @param callback  异步回调
     */ GameBoxManager.getInstance(this).applyCloudDevice(@NonNull GameInfo gameInfo, boolean playQueue,

 @NonNull new APICallback<DeviceControl>(){ @Override public void

 onAPICallback(DeviceControl deviceControl, int code) { //回调 } })

获取排队进度

在游戏成功进入排队以后，可以定时检测队列状态

/**
     * 加入队列，获取队列状态
     *
     * @param gameInfo      游戏信息
     * @param checkInterval 队列检测时间间隔，单位秒
     * @param callback      回调
     */ GameManager.getInstance(this).joinQueue(GameInfo gameInfo, int checkInterval, APICallback<QueueRankInfo> callback); /** 

 如需使用脚本,可以传入scriptMap
     * @param tagKey     分组标签
     * @param scriptMap     脚本map
     */ GameManager.getInstance(this).joinQueue(GameInfo gameInfo, int checkInterval,

 APICallback<QueueRankInfo> callback,String tagKey,HashMap<String,Object> scriptMap);

添加多个队列监听调用 DeviceControl：

/**
     * 注册排队监听回调
     * @param callback 回调
     */ public void registerQueueCallback(APICallback<QueueRankInfo> callback);

可以通过监听回调，获取当前队列的状态进度和事件 队列信息：

public class QueueRankInfo { //游戏信息 public GameInfo gameInfo; //当前排名 public int queueRanking;

 //预估时间，单位毫秒，不准确 public long queueWaitTime; }

队列事件：

/** 队列更新 */ public static final int QUEUE_UPDATE = 1004; /**

 队列加速前 */ public static final int QUEUE_ACCELERATE_BEFORE = 1005; /** 队列加速后

 */ public static final int QUEUE_ACCELERATE_AFTER = 1006; /** 排队成功 */

 public static final int QUEUE_SUCCESS = 1007; /** 队列退出 */

 public static final int QUEUE_EXIT = 1008; /** 排队失败 */ public static final int QUEUE_FAILED = 1009;

 /** 不存在队列，直接申请*/ public static final int QUEUE_NO_QUEUE = 1010;

队列加速

为了配合产品策略，提供队列加速功能，

/**
     * 队列加速
     * @param accCount 加速前进数量
     */ GameManager.getInstance(this).accelerateQueue(int accCount) /** 如需使用脚本,可以传入scriptMap
     * @param scriptMap     脚本map
     * @param tagKey     分组标签
     */ GameManager.getInstance(this).accelerateQueue(int accCount, String tagKey, HashMap< String, Object > scriptMap);

退出队列

退出队列接口，如果退出试玩，一定要调用此接口，否则肯会内存泄漏

/**
     * 退出队列
     */ GameManager.getInstance(this).exitQueue() /**
     * 指定标签退出队列
     */ GameManager.getInstance(this).exitQueue(String tagKey) 

跨进程调用

为了方便开发者使用SDK在不同进程中启动云游戏，例如：A进程排队申请设备，B进程启动云游戏，

支持通过传递设备TOKEN方式完成跨进程调用，TOKEN有效期2分钟。

获取Token

在申请设备成功之后，通过DeviceControl获得设备Token：

/**
     * 生成设备连接信息，用于跨进程调用
     *
     * @return
     */ public String getDeviceToken();

通过Token连接

Token有效期2分钟，如果Token过期会返回

APIConstants.ERROR_DEVICE_TOKEN_VALID_FAILED

1、先通过Token重新获取DeviceControl：

/**
     *  根据已有设备Token还原设备链接信息
     * @param deviceToken 设备token
     * @param callback 回调
     */ GameBoxManager.getInstance(this).applyCloudDeviceWithToken(String deviceToken,

 @NonNull new APICallback<DeviceControl>(){ @Override public void onAPICallback(DeviceControl deviceControl, int code) { //回调 } })

2、启动云游戏

参照启动云游戏

数据通道

数据通道是指在用户手机和云手机之间的一个长连接，用于文本数据上下行数据传输，数据进行加密，

方便开发者进行和远程App的通讯。可用于远程登录、远程支付（H5）、消息传递等。

客户端发送数据

在申请设备成功之后，通过DeviceControl发送数据，数据内容以Key-Value形式发送。

/**
 * 向当前启动的云手机App发送消息，消息格式自定义
 *
 * @param map
 */ public abstract void sendMessageToDevice(Map<String, String> data);

客户端接收数据

在申请设备成功之后，通过DeviceControl注册DataTransferListener监听，接收云手机发送的数据。

/**
     * 注册监听，接收云手机App返回的消息
     *
     * @param listener
     */ public abstract void registerDataTransferListener(DataTransferListener listener); /**
     * 云手机消息接收监听
     */ public interface DataTransferListener { /**
         * 接收到云手机消息回掉
         *
         * @param data 消息未自定义格式
         */ void onReceiveData(Map<String, String> data); /**
         * 消息发送失败
         *
         * @param code
         */ void onSendFailed(int code); }

云手机收发数据

参照百度云游戏帐号互通SDK文档

传感器采集

传感器采集，是将本地的传感器信息采集后发送到云手机上进行还原，达到本地与云手机一致。目前支持采集得传感器包含麦克风、摄像头、陀螺仪、加速器等。

备注：

1. 麦克风和摄像头包含采集、编码、传输、还原、渲染等步骤，目前摄像头对480P（800*480）支持效果较好（1-2s），720p支持待优化。
2. 音视频编码需要根据设备类型和需求进行适配，因此采集、编码需要开发者自行根据DEMO中hardware模块进行调整开发。

传感器回调

在申请到设备之后，注册此监听，当云手机App使用到相关传感器之后，会进行回调。 回调包含：硬件ID（SensorConstants.CloudPhoneSensorId）、硬件状态（SensorConstants.SensorState）

/**
     * 注册监听，接收硬件采集信息
     *
     * @param listener
     */ public abstract void registerSensorSamplerListener(SensorSamplerListener listener); /**
     * 采集硬件信息回掉
     */ public interface SensorSamplerListener { /**
         * 采集硬件信息状态发生变化
         *
         * @param sensor 硬件类型  @SensorConstants.CloudPhoneSensorId
         * @param state  硬件状态  @SensorConstants.SensorState
         */ void onSensorSamper(@SensorConstants.CloudPhoneSensorId int sensor, @SensorConstants.SensorState int state); }

传感器数据发送

将本地数据发送至传感器，需要指定传感器类型和数据类型，具体参照DEMO

/**
     * 发送硬件信息，此接口针对摄像头和麦克风数据
     *
     * @param type 硬件类型 @{@SensorConstants.CloudPhoneSensorId}
     * @param type 数据@{@SensorConstants.CameraVideoType}
     * @return
     */
    public abstract void sendSensorInputData(@SensorConstants.CloudPhoneSensorId int sendor,
                                             @SensorConstants.AudioType @SensorConstants.CameraVideoType int type,
                                             byte[] data);

    /**
     * 发送硬件传感器信息，此接口针对陀螺仪、加速器、重力感应等传感器
     * @param sendor 传感器id @{@SensorConstants.CloudPhoneSensorId}
     * @param sensorType @{传感器类型 SensorConstants.SensorType}
     * @param data 传感器数据参数
     */
    public abstract void sendSensorInputData(@SensorConstants.CloudPhoneSensorId int sendor,
                                             @SensorConstants.SensorType int sensorType,
                                             float... data);

云手机信息修改

为了方便支持客户端同步设备信息，目前支持将IMEI、AndroidID同步到云手机上。需要在启动游戏之前设置,每次设置只当次启动生效 (added v1.5.3)

调用GameManager方法，在申请设备之进行设置。

备注：由于修改硬件信息为异步操作，成功率为99%

/**
     * 设置云手机参数信息，需要在申请设备之前进行设置
     *
     * @param key   目前支持imei，androidid
     * @param value
     */ public void addDeviceMockInfo(String key, String value) { mMockInfo.put(key, value); } /**
     * 移除云手机参数信息
     *
     * @param key 目前支持imei，androidid设置
     */ public void removeDeviceMockInfo(String key) { mMockInfo.remove(key); }

DeviceMockInfo里面有目前支持的key

DeviceMockInfo支持key,目前支持字段如下(后期可能会扩展，扩展之后直接添加相应字段,方法不变):

DEMO示例集成

为了方便大家快速开发使用云游戏SDK，我们在SDK中附带了一个DEMO，供大家参考使用，可以根据DEMO稍做修改快速集成到自己的产品中。

DemoApplication : 将 onCreate中初始化sdk复制到产品自定义的Application完成初始化。

HomeActivity：主界面，包含一个游戏列表，以及下拉刷新，可以进行自定义。

GameRunningActivity：试玩界面，已经完成了出下载外的所有逻辑，可以在downloadApp(String pkgName)加上调用App下载模块的逻辑。

附录

状态码说明

SDK提交记录

主版提交记录：

• 20190315: v1.0 首次提交
• 20190329: v1.1 so初始化延后至游戏启动，增加渠道
• 20190418: v1.1.5 增加数据统计能力
• 20190830: v1.2.0 增加PlayListener，增加无操作超时设置。
• 20191111: v1.3.0 增加排队机制
• 20200210: v1.4.0 增加数据互通能力
• 20200309: v1.5.0 增加传感器采集能力
• 20200415: v1.5.3 增加IMEI、AndroidID同步、Location传感器虚拟、修改无操作超时逻辑试玩设置、READ_PHONE_STATE权限移除
• 20200827: v1.5.4 迁移到新SaaS平台,新增通过游戏名称获取运营平台配置的游戏列表,新增获取默认分辨率设置
• 20210115: v1.5.5 云手机和云游戏sdk合并,并且支持新老pass平台切换