云手机BAC

    云游戏 Android SDK

    云游戏Android SDK文档v1.5.4

    云游戏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下载

    运行环境

    可运行于 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();

    设置声音开关

        /**
         * 试玩声音开关
         * @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(@APIConstants.MockInfo String key, String value) {
            mMockInfo.put(key, value);
        }
        
        /**
         * 移除云手机参数信息
         *
         * @param key 目前支持imei,androidid设置
         */
        public void removeDeviceMockInfo(@APIConstants.MockInfo String key) {
            mMockInfo.remove(key);
        }

    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平台,新增通过游戏名称获取运营平台配置的游戏列表,新增获取默认分辨率设置
    上一篇
    快速入门
    下一篇
    OPEN API参考