手游单机版接入手册 for Android


1. 前言

本文用于指导单机游接入SDK,文中包含客户端的接入说明;

2. SDK接入流程概述

  • 搭建SDK开发环境

  • 初始化SDK

  • 初始化成功,调用登录功能相关接口

  • 用户在进行购买时,调用支付功能相关接口

  • 其他功能接口如上传存档等,可根据业务需要适时调用

  • 销毁SDK

3. 开发环境要求

3.1. 集成SDK文件到游戏工程

  • 将压缩包中的assets目录下的所有文件和文件夹拷贝到游戏工程的assets目录下。
  • 将压缩包中的libs目录下的所有文件和文件夹拷贝到游戏工程的libs目录下。
  • 将压缩包中的res目录下的所有文件和文件夹拷贝到游戏工程的res目录下。

3.2. 配置AndroidManifest.xml文件

  • 请在游戏工程的AndroidManifest.xml文件中增加以下权限:
       <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/>
    <uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

注意:如果文档和SDK中的AndroidManifest.xml文件存在差异,请以SDK中的文件为准!且android:targetSdkVersion必须小于23

3.3 回调状态码说明

public class ErrorCode {
    //请求成功
    public final static int ERROR_OK = 0;
    //ticket过期或失效
    public final static int ERROE_TICKET_TIMEOUT = 3001;
    //gtoken过期或失效
    public final static int ERROR_GTOKEN_INVALID = 67;
    //当前appid为空
    public final static int ERROR_EMPTY_APPID = -2;
    //请求失败
    public final static int ERROR_FAILED = -1;

}

注:回调状态码定义在SDK的ErrorCode类中,可直接通过“类名.状态码”调用。

4. 基础功能(必接)

4.1. SDK接口统一回调

  • 接口定义:

    callback(int code, String message, Map data);

  • 参数说明:

    code: 为回调状态码,等于0时表示成功,其余说明见回调状态码说明。

    message: 为回调状态的描述,如接口调用失败时的错误描述。

    data: 为回调的结果数据。

  • 接口代码:
public interface GameSDKCallback {
    void callback(int code, String message, Map<String, String> data);
}

4.2. 初始化接口

游戏客户端在接入时,调用其他API前需先调用initialize初始化接口,对SDK进行初始化。

  • 接口:

    initialize(String appId, GameSDKCallback callback);

  • 参数说明:

    appId: 游戏ID。

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 注意事项:

    如果没有特别说明,在初始化接口成功之前调用其他接口都有可能出现错误,请确保初始化接口成功之后再调用其他接口。

  • 代码示例:
GameSDK.getInstance().initialize(appid, new GameSDKCallback() {
    @Override
    public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
        //初始化成功调用            
        }else{
        //初始化失败调用
        }
    }
});

4.3. 登录接口

游戏客户端需要在登录时调用该接口。

  • 接口:

    login(final Context context,String areaId, String groupId, String ticket, final GameSDKCallback callback)

  • 参数说明:

    context: Context对象。

    areaid: 区服ID。

    groupId: 组群ID,若游戏无该参数,则默认传0。

    ticket: 票据

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().login(context,areaId, groupId, ticket, new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
            //登录成功时调用            
        }else if(code==ErrorCode.ERROR_EMPTY_APPID){
            //appid为空,请初始化时传入正确的appid

        }else if(code == ErrorCode.ERROE_TICKET_TIMEOUT){
            //票据失效或过期

        }else{
            //登陆失败
        }
     }
 });
  • 注意事项:

    调用SDK登录接口,需先调用SDK初始化接口。需要在游戏登录成功获取ticket之后调用,具体什么位置调用由接入方自行决定,只要保证在SDK登录成功后才能调用其它业务接口,推荐在游戏登录成功之后立即调用。若ticket过期或失效,接入方需要重新调用接口获取新的ticket。

4.4. 注销接口

游戏客户端需要在注销时调用该接口。

  • 接口:

    logout(GameSDKCallback callback)

  • 参数说明:

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().logout(new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
        //注销成功时调用            
        }else{
        //注销失败时调用
        }
     }
 });
  • 注意事项:

    调用SDK注销接口后,将会清除账户相关数据,无法正常调用其它业务接口。

4.5. 判断当前网络状态

游戏客户端需要判断当前网络状态时调用该接口

  • 接口:

    isNetworkAvailable(Context context, GameSDKCallback callback)

  • 参数说明:

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
    GameSDK.getInstance().isNetworkAvailable(context, new GameSDKCallback() {
            @Override
            public void callback(int code, String message, Map<String, String> data) {
              if(code==ErrorCode.ERROR_OK){
                 ToastUtil.showMessage(MainActivity.this,"网络可用,网络类型为:"+data.get("networkState"));
              }else{
                 ToastUtil.showMessage(MainActivity.this,"网络不可用");
              }
         }
     });
  • 注意事项:

    该接口回调的code=ErrorCode.ERROR_FAILED表示当前网络不可用,code=ErrorCode.ERROR_OK时表示当前网络可以,在data中可通过data.get("networkState")获取网络类型,其中:

      data.get("networkState") == "WiFi" 表示wifi无线网
      data.get("networkState") == "WWAN" 表示手机4G、3G、2G等网络

5. 存档功能(必接)

5.1. 上传存档接口

游戏客户端上传存档时调用该接口。

  • 接口:

    public void uploadSavedata(final Context context,String filePath, final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    filePath: 存档所在的路径,为存档在手机内存中的地址,如:/storage/emulated/0/demo.txt

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().uploadSavedata(context,filePath, new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
        //上传成功时调用            

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
        //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
        //上传失败时调用

        }
     }
 });

5.2. 下载存档接口

游戏客户端下载存档时调用该接口。

  • 接口:

    public void downloadSavedata(final Context context,final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().downloadSavedata(context,new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
            //下载成功时调用        
            String filepath= data.get("filepath");
            File downfile = new File(filepath);

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
            //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
            //下载失败时调用
        }
     }
 });
  • 返回结果说明

    下载成功时,存档将被下载到手机磁盘中,在callback的返回值data中通过data.get("filePath")即可获得存档的保存地址

6 订单信息处理接口

6.1. 获取支付待发货订单信息接口

游戏客户端获取待发货订单信息时调用该接口。

  • 接口:

    public void requestUndeliveredOrderInfo(final Context context,final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().requestUndeliveredOrderInfo(context,new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
            //获取成功时调用            
        String orderList = data.get("orderList");

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
        //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
        //获取失败时调用

        }
     }
 });
  • 返回结果说明

    订单信息获取成功时将在data集合中返回,可通过data.get("orderList")获得订单信息的字符串,字符串为Json格式 示例:

     [
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
       ...
     ]

6.2. 上报已支付的发货订单的发货结果接口

游戏上报已支付的发货订单的发货结果时调用该接口。

  • 接口:

    public void reportOrderResult(final Context context,List orderList, final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    orderList: 要上报的订单信息,为存储订单号的List集合

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().reportOrderResult(context,orderList, new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
            //上报成功时调用        

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
        //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
        //上报失败时调用

        }
     }
 });
  • 返回结果说明

7 领奖信息处理接口

7.1. 获取领奖待发货订单信息接口

游戏客户端领奖待发货订单信息时调用该接口。

  • 接口:

    public void requestAwardInfo(final Context context,final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().requestAwardInfo(context,new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ERROR_OK){
            //获取成功时调用            
        String orderList = data.get("orderList");

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
        //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
        //获取失败时调用

        }
     }
 });
  • 返回结果说明

    订单信息获取成功时将在data集合中返回,可通过data.get("orderList")获得订单信息的字符串,字符串为Json格式 示例:

     [
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
      {"orderId":"","traceNo":"","areaId":"","productId":"","quantity":"","extend":""},
       ...
     ]

7.2. 上报已发货领奖订单接口

游戏上报已发货领奖订单时调用该接口。

  • 接口:

    public void reportAwardResult(final Context context,List orderList, final GameSDKCallback callback)

  • 参数说明:

    context: Context对象

    orderList: 要上报的订单信息,为存储订单号的List集合

    callback: 回调对象,用来回调执行结果,详情请参考代码事例。

  • 代码示例:
   GameSDK.getInstance().reportAwardResult(context,orderList, new GameSDKCallback() {
     @Override
     public void callback(int code, String message, Map<String, String> data) {
        if(code == ErrorCode.ERROR_OK){
            //上报成功时调用        

        }else if(code == ErrorCode.ERROR_GTOKEN_INVALID){
        //gtoken过期或失效时调用,此时需要接入方重新调用初始化、登录接口

        }else{
        //上报失败时调用

        }
     }
 });