云游戏 Android SDK
所有文档

          云手机BAC

          云游戏 Android SDK

          云游戏Android SDK文档v1.5.5

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

          简介

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

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

          云游戏 SDK 下载


          版本号 更新时间 下载地址 备注
          V1.5.4.0 2020.09.07 Android SDK下载
          V1.5.4.5 2021.01.15 Android SDK下载

          运行环境

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

          SDK导入及配置

          申请APPID

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

          导入aar包

          SDK包含gameboxlib-veriosn-xxx.aarandroid-support-v4.jar,请将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.redfinger.playsdk.fragment.**{*;}
          -keep class com.redfinger.playsdk.widget.**{*;}
          -keep class com.gc.redfinger.** { *; }

          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_SUCCESSDeviceControl用于控制设备,否则返回对应错误码。

          GameBoxManager.getInstance(this).applyCloudDevice(@NonNull GameInfo gameInfo, 
          	@NonNull new APICallback<DeviceControl>(){
          	            @Override
                      public void onAPICallback(DeviceControl deviceControl, int code) {
                          //回调
                      }
          	})

          启动游戏试玩

          在设备申请成功后,可使用返回的DeviceControl启动游戏试玩。游戏试玩界面需要添加到一个FragmentActivity中,需要传入ViewGroupid供添加试玩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 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 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);

          退出试玩

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

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

          排队机制

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

          设置会员等级

          会员等级分为普通会员MemberLevel.NORMAL、VIP会员MemberLevel.VIP、超级VIP会员MemberLevel.SUPER_VIP,默认为普通会员。开发者可以与自己的会员体系进行映射,会议会影响加速效果,在加速之前可通过GameBoxManager先进行全局的会员等级设置。

             /**
               * 设置会员等级
               *
               * @param memberLevel
               */逻辑
              public void setMemberLevel(MemberLevel memberLevel) {
                  mMemberLevel = memberLevel;
              }
          
              /**
               * 获取当前会员等级
               *
               * @return
               */
              public MemberLevel getMemberLevel() {
                  return mMemberLevel;
              }

          申请排队

          申请设备时playQueuetrue在设备不足的情况下会进入排队状态,返回状态码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);

          添加多个队列监听调用 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)

          退出队列

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

            /**
               * 退出队列
               */
              public void exitQueue() 

          跨进程调用

          为了方便开发者使用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文档 http://wiki.baidu.com/pages/viewpage.action?pageId=1230130857

          传感器采集

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

          备注:

          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);

          云手机信息修改

          为了方便支持客户端同步设备信息,目前支持将IMEIAndroidID同步到云手机上。需要在启动游戏之前设置,每次设置只当次启动生效 (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,目前支持字段如下(后期可能会扩展,扩展之后直接添加相应字段,方法不变):

          字段 说明
          brand 品牌
          model 设备型号
          manufacturer 厂商
          wifimac Wifi mac 物理地址
          serialno 序列号
          baseband 基带
          board 主板名
          displayId 显示的版本号,可以任意修改,显示为手机信 息的内部版本号
          device 设备名
          fingerprint 系统指纹
          productName 产品名称
          buildId build 的版本号
          buildHost 系统主机名,
          bootloader 品牌
          buildTags 系统标记
          buildType 系统编译类型
          buildVersionInc 版本的增加说明
          buildDescription 编译备注
          imei 序列号(串号)
          phonenum 电话号码
          iccid SIM 卡卡号
          imsi 用户识别码
          imeisv 国际移动设备标识码软件版本
          wifiname wifi 名称
          bssid MAC 物理地址
          androidid 厂商自定义的一个字符串

          DEMO示例集成

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

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

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

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

          附录

          状态码说明

          代码 含义
          APPLY_DEVICE_SUCCESS 1000 设备申请成功
          CONNECT_DEVICE_SUCCESS 1001 设备连接成功代码
          RECONNECT_DEVICE_SUCCESS 1002 设备重连成功
          WAITING_QUEUE 1003 当全无设备,需要排队
          QUEUE_UPDATE 1004 队列更新
          QUEUE_ACCELERATE_BEFORE 1005 队列加速前
          QUEUE_ACCELERATE_AFTER 1006 队列加速后
          QUEUE_SUCCESS 1007 排队完成
          QUEUE_EXIT 1008 队列退出
          QUEUE_FAILED 1009 排队失败
          QUEUE_NO_QUEUE 1010 排队失败
          ERROR_API_CALL_ERROR -1000 API调用失败
          ERROR_NO_DEVICE -1001 无设备
          ERROR_NETWORK_ERROR -1002 网络错误
          ERROR_DEVICE_EXPIRED -1003 设备过期
          ERROR_DEVICE_OTHER_ERROR -1004 申请设备未知错误
          ERROR_OTHER_DEVICE_RUNNING -1005 有未释放的设备实例
          ERROR_SDK_INIT_ERROR -1006 播放SDK初始化失败
          ERROR_APP_QUERY_ERROR -1007 应用信息获取失败
          ERROR_WAITING_QUEUE -1008 游戏启动失败,正在排队
          ERROR_OTHER_DEVICE_WAITING -1009 有其他游戏正在排队,无法排队
          ERROR_DEVICE_TOKEN_VALID_FAILED -1010 通过DeviceToke跨进程重连错误

          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平台切换
          上一篇
          快速入门
          下一篇
          OPEN API参考