EYuanCommSdk-KTX

[TOC]

修订记录

日期	版本	说明	作者
2022-02-28	1.0.0	文档建立	麦锦培

1.接入前检查

• 游戏资源文件名、布局名、布局id名等建议使用规范命名，避免和SDK资源冲突

• Android Studio 3.0及以上，由于谷歌服务一系列SDK已不提供jar包形式，因此SDK不提供jar包形式以eclipse接入

• Android Gradle Plugin Version : 7.0.2+

• Gradle Version : 7.0.2+

• Android Studio开启Android X支持，请在游戏项目根目录的gradle.properties中设置

  android.useAndroidX=true
  android.enableJetifier=true

• 请务必使用我们提供的keystore签名文件进行签名，否则SDK功能会异常

• 服务端接口文档

• 客户端SDK接入Demo

2.SDK资源接入说明

• 1.接入中存在问题请参考SDK提供的Demo工程或联系技术解决

• 2.拷贝对应渠道目录下assets至项目中

• 3.拷贝对应渠道目录下res/values/strings.xml中的内容至项目中相应的文档中，如果没有strings.xml则新建一份即可，如果该目录没有则不需要处理

• 4.在应用build.gradle中dependencies节点下添加SDK依赖，目前只提供远程依赖

在项目级build.gradle文件下的allprojects节点下添加仓库的url

      allprojects {
          repositories {
              ...
              mavenCentral()
              // 华为sdk仓库
              maven { url 'https://developer.huawei.com/repo' }
              ...
          }
      }

在应用级build.gradle文件下的allprojects节点下添加仓库的url

    implementation 'io.github.yyxxgame.sdk:eyuancomm-sdk-ktx-comm:1.0.0-rc3'
    implementation 'io.github.yyxxgame.sdk:eyuancomm-sdk-ktx-impl:1.0.0-rc3'
    // 以下sdk依赖在生成对应包时按需引入，为了避免资源冲突请不要同时引入
    implementation 'io.github.yyxxgame.sdk:eyuancomm-channel-lib-huawei:1.0.0-rc3'
    implementation 'io.github.yyxxgame.sdk:eyuancomm-channel-lib-oppo:1.0.0-rc3'

3.接口说明

SDK的所有接口如无特殊说明，默认均为必接且请务必在游戏主线程调用

1）同步Application中的生命周期

• 若游戏无自定义Application则直接在清单文件AndroidManifest.xml的application节点中设置name属性为SDK提供的Applicationcn.yyxx.eyuangame.base.EYuanCommApplication

    <application android:name="cn.yyxx.eyuangame.base.EYuanCommApplication">
        ···
    </application>

• 若游戏有自定义Application，则需要继承SDK提供的Application

    public class DemoApplication extends EYuanCommApplication {
        @Override
        protected void attachBaseContext(Context base) {
            super.attachBaseContext(base);
        }

        @Override
        public void onCreate() {
            super.onCreate();
        }
    }

2）同步游戏Activity中各个生命周期至SDK

• 同步onStart

    @Override
    protected void onStart() {
        super.onStart();
        EYuanCommSdk.getInstance().onStart(this);
    }

• 同步onResume

    @Override
    protected void onResume() {
        super.onResume();
        EYuanCommSdk.getInstance().onResume(this);
    }

• 同步onRestart

    @Override
    protected void onRestart() {
        super.onRestart();
        EYuanCommSdk.getInstance().onReStart(this);
    }

• 同步onPause

    @Override
    protected void onPause() {
        super.onPause();
        EYuanCommSdk.getInstance().onPause(this);
    }

• 同步onStop

    @Override
    protected void onStop() {
        super.onStop();
        EYuanCommSdk.getInstance().onStop(this);
    }

• 同步onDestroy

    @Override
    protected void onDestroy() {
        super.onDestroy();
        EYuanCommSdk.getInstance().onDestroy(this);
    }

• 同步onActivityResult

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        EYuanCommSdk.getInstance().onActivityResult(this, requestCode, requestCode, data);
    }

• 同步onNewIntent

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        EYuanGame.getInstance().onNewIntent(this, intent);
    }

3）SDK通用回调接口ICallback说明

    public interface ICallback {
        void onResult(int code, String result);
    }

参数	类型	说明
code	int	状态码（0成功，-1失败）
result	string	返回信息

4）SDK初始化

• 在游戏的主Activity的onCreate中调用

    /**
     * SDK初始化
     *
     * @param activity    Activity上下文
     * @param isLandscape 是否横屏
     * @param callback    SDK初始化回调
     */
    public void initialize(final Activity activity, final Boolean isLandscape, ICallback callback)

• 示例

    @Override
    protected void onCreate(Bundle savedInstanceState){
        EYuanCommSdk.getInstance().initialize(this, false, new ICallback() {
            @Override
            public void onResult(int code, String result) {
                if (code == 0) {
                    //TODO SDK初始化成功
                } else {
                    //TODO SDK初始化失败，result是失败的debug信息
                }
            }
        });
    }

5）用户账号登录

    /**
     * SDK用户登录
     *
     * @param activity Activity上下文
     * @param isAuto   是否自动登录
     * @param callback 登录回调对象
     */
    public void login(Activity activity, Boolean isAuto, ICallback callback)

登录回调返回的result信息

参数	类型	说明
userId	string	SDK的用户ID
token	string	签名token

• 示例

    EYuanCommSdk.getInstance().login(DemoActivity.this, true, new ICallback(){
        @Override
        public void onResult(int code, String result) {
            if (code == 0) {
                //TODO 对SDK返回的用户信息进行验签
                //result返回的是JSON字符串，可以得到uid和token等信息
                //签名规则详见服务端接入文档
            } else {
                //TODO 登录失败，result是返回的debug信息
            }
        }
    });

6）用户账号登出

用户在游戏中触发登出，游戏回到选服界面重新拉起登录

    /**
     * SDK用户登出账号
     *
     * @param activity Activity上下文
     * @param callback 登出回调对象
     */
    public void logout(Activity activity, ICallback callback)

• 示例

    EYuanCommSdk.getInstance().logout(this, new ICallback() {
        @Override
        public void onResult(int code, String result) {
            if (code == 0) {
                //TODO 用户登出成功，登出成功后请返回游戏选服界面，然后拉起登录框，如果调用登录接口，请设置为非自动登录
            } else {
                //TODO 用户登出失败，result是返回的debug信息
            }
        }
    }

7）角色信息上报

请务必根据当前角色的触发的事件进行上报

角色信息实体对象SdkRoleInfo，如无特别说明所有字段均不能为null或空串""

参数	类型	说明
userId	string	当前用户ID
serverId	string	当前角色所在的服务器ID
serverName	string	当前角色所在的服务器名
roleId	string	当前角色ID
roleName	string	当前角色名
roleLevel	string	当前角色等级
roleCTime	long	当前角色创建的时间戳（10位），角色一旦创建则是固定值
vipLevel	string	当前Vip角色等级，若无传"none"
balance	string	当前角色游戏币余额，若无传"none"
totalPurchase	int	累计充值金额，若无传0）

角色创建

    /**
     * SDK角色创建信息上报
     *
     * @param activity Activity上下文
     * @param roleInfo 角色信息实体
     */
    public void roleCreate(Activity activity, SdkRoleInfo roleInfo)

角色进入服务器（角色登录）

    /**
     * SDK角色登录信息上报
     *
     * @param activity Activity上下文
     * @param roleInfo 角色信息实体
     */
    public void roleLauncher(Activity activity, SdkRoleInfo roleInfo)

角色升级

    /**
     * SDK角色升级信息上报
     *
     * @param activity Activity上下文
     * @param roleInfo 角色信息实体
     */
    public void roleUpgrade(Activity activity, SdkRoleInfo roleInfo)

• 示例

    SdkRoleInfo gameRoleInfo = new SdkRoleInfo();
    //用户ID
    gameRoleInfo.setUserId(EYuanGame.getInstance().getCurrentUserId());
    //角色ID
    gameRoleInfo.setRoleId(roleId);
    //角色名称
    gameRoleInfo.setRoleName(roleName);
    //角色等级
    gameRoleInfo.setRoleLevel(roleLevel);
    //创角时间戳（角色一旦创角则是固定值）
    gameRoleInfo.setRoleCTime(System.currentTimeMillis()/1000)
    //服务器ID
    gameRoleInfo.setServerId(serverId);
    //服务器名
    gameRoleInfo.setServerName(serverName);
    //用户VIP等级，无该字段则传空串""
    gameRoleInfo.setVipLevel("1");
    //当前角色游戏币余额
    gameRoleInfo.setBalance("600");
    //累计充值金额，若无传0）
    gameRoleInfo.setTotalPurchase(0)

    //角色创建
    EYuanCommSdk.getInstance().roleCreate(this, gameRoleInfo);

    //角色登录
    EYuanCommSdk.getInstance().roleLauncher(this, gameRoleInfo;

    //角色升级
    EYuanCommSdk.getInstance().roleUpgrade(this, gameRoleInfo;

8）支付储值

请务必保证调用角色信息上报中的角色登录上报后再调用 客户端SDK回调的只是支付流程的结果，实际支付结果将由服务端回调 默认情况均为内购包即上架Google Play，具体情况请根据运营需求接入

支付信息实体对象SdkChargeInfo，如无特别说明所有字段均不能为null或空串""

参数	类型	说明
userId	string	当前用户ID
serverCode	string	当前角色所在的服务器ID
serverName	string	当前角色所在的服务器名
roleId	string	当前角色ID
roleName	string	当前角色名
roleLevel	string	当前角色等级
amount	int	金额，单位分，币种固定为币种美金
productId	string	商品ID
productName	string	商品名称
productDesc	string	商品描述
cpOrderId	string	游戏订单号
cpExt	string	游戏透传信息，最终会元游返回，可为空
cpPayTime	long	下单时间，10位Unix时间戳
cpPaySign	string	支付签名，具体签名规则详见服务端接口文档

    /**
     * SDK用户支付
     *
     * @param activity   Activity上下文
     * @param chargeInfo 支付信息实体对象
     * @param isIab             是否内购
     * @param callback   支付回调对象
     */
    public void charge(Activity activity, SdkChargeInfo chargeInfo, boolean isIab , ICallback callback)

• 示例

    long ts = System.currentTimeMillis();
    SdkChargeInfo gameChargeInfo = new SdkChargeInfo();
    //用户ID
    gameChargeInfo.setUserId(EYuanGame.getInstance().getCurrentUserId());
    //角色ID
    gameChargeInfo.setRoleId(roleId);
    //角色名称
    gameChargeInfo.setRoleName(roleName);
    //角色等级
    gameChargeInfo.setRoleLevel(roleLevel);
    //创角时间戳（角色一旦创建则是固定值）
    gameChargeInfo.setRoleCTime(创角时间戳（角色一旦创建则是固定值）);
    //服务器ID
    gameChargeInfo.setServerId(serverId);
    //服务器名
    gameChargeInfo.setServerName(serverName);
    //游戏的订单号
    gameChargeInfo.setCpOrderId(orderId);
    //透传字段，会在服务端回调中原样返回
    gameChargeInfo.setCpExt("cp_callback_info||" + orderId);
    //金额，单位分，币种美金
    gameChargeInfo.setAmount(99);
    //商品ID，计费点
    gameChargeInfo.setProductId("com.shzd.1usd");
    //商品名称
    gameChargeInfo.setProductName("60元宝");
    //商品描述
    gameChargeInfo.setProductDesc("60元宝");
    //下单时间
    gameChargeInfo.setCpPayTime(payTs)
    //支付签名
    gameChargeInfo.setCpPaySign("支付签名，具体签名规则详见服务端接口文档")

    //客户端SDK回调的只是支付流程的结果，实际支付结果将由服务端回调
    EYuanCommSdk.getInstance().charge(this, gameChargeInfo, true , new ICallback() {
        @Override
            public void onResult(int code, String result) {
                if (code == 0) {
                    //TODO 支付流程完成
                } else {
                    //TODO 支付失败
                }
            }
    });

9）显示SDK退出框

用户（玩家）按下返回键时调用，接入方需要实现Activity的onKeyDown，并判断keyCode为KeyEvent.KEYCODE_BACK时调用该接口

调用退出框前，请先调用hasExitView()判断是否有渠道退出框，如果返回false则显示游戏原生退出框即可

    /**
     * 显示退出框
     *
     * @param activity Activity上下文
     * @param callback 退出回调对象
     */
    public boolean hasExitView(Activity activity)

    /**
     * 显示退出框
     *
     * @param activity Activity上下文
     * @param callback 退出回调对象
     */
    public void openExitView(Activity activity, ICallback callback)

• 示例

    //重写Activity的onKeyDown并判断KeyDown事件
    @Override
    public boolean onKeyDown(int keyCode, KeyEvent event) {
        if (keyCode == KeyEvent.KEYCODE_BACK) {
            if (EYuanCommSdk.getInstance().hasExitView(this)) {
                EYuanCommSdk.getInstance().openExitView(this, new ICallback() {
                    @Override
                    public void onResult(int code, String result) {
                        if (code == 0) {
                            // 结束当前Activity
                            // 如果要杀进程需要在onDestroy中处理，不然会不执行SDK的onDestroy方法
                            finish();
                        }
                    }
                });
            }else {
                // 显示游戏原生退出框
            }
            return true;
        }
        return super.onKeyDown(keyCode, event);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        EYuanCommSdk.getInstance().onDestroy(this);
        //结束当前应用进程
        System.exit(0);
    }

10）设置SDK浮标切换用户监听

在SDK初始化成功后设置浮标切换用户监听

    /**
     * 设置SDK浮标切换用户监听
     *
     * @param callback 切换用户回调对象
     */
    public void setOnFloatBallLogout(ICallback callback)

• 示例

    EYuanCommSdk.getInstance().initialize(this, true, new ICallback() {
        @Override
        public void onResult(int code, @NonNull String result) {
            if (code == 0) {
                // SDK初始化成功设置浮标切换用户监听
                EYuanCommSdk.getInstance().setOnFloatBallLogout(new ICallback() {
                    @Override
                    public void onResult(int code2, @NonNull String result2) {
                        if (code2 == 0) {
                            // 用户触发浮标切换账号，游戏需退回到登录选服页，并调用SDK的login()接口拉起登录
                         } else {
                            // 预留，暂时无需处理
                        }
                    }
                });
            }
        }
    });

11）获取SDK当前用户ID（选接）

    /**
     * 获取当前SDK版本
     *
     * @return
     */
    public String getCurrentUserId()

• 示例

    EYuanCommSdk.getInstance().getCurrentUserId();

12）获取SDK当前版本（选接）

    /**
     * 获取当前SDK版本
     *
     * @return
     */
    public String getCurrentSdkVersion()

• 示例

    EYuanCommSdk.getInstance().getCurrentSdkVersion();

13）SDK日志接口（选接）

若游戏有需要持久化java、kotlin和C++(联系我方技术获取头文件)层的日志，可以使用SDK的日志接口。SDK的日志框架底层使用C++进行开发，使用了Linux系统的mmap内存拷贝技术 SDK会默认缓存3天的日志，过期则自动删除 缓存的文件使用Facebook开源的压缩算法zlib进行压缩 缓存路径为手机内部存储目录/Android/data/包名/files/dolin/zap，即应用的私有目录 更多使用方法请联系我方技术

    // debug日志
    Logger.d(TAG,msg);
    // info日志
    Logger.i(TAG,msg);
    // error日志
    Logger.e(TAG,msg);