EYuanCommSdkDemo

修订记录

日期	版本	说明	作者
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-rc6'
    implementation 'io.github.yyxxgame.sdk:eyuancomm-sdk-ktx-impl:1.0.0-rc4'

    // 以下sdk按接入需求引入，注意不能同时引入

    // 元游sdk（谷歌包官网包）
    implementation 'io.github.yyxxgame.sdk:eyuancomm-sdk-ktx-core:1.0.0-rc5'
    // 以下sdk依赖在生成对应包时按需引入，为了避免资源冲突请不要同时引入
    // 元游sdk港台繁体语言包
    implementation 'io.github.yyxxgame.sdk:eyuancomm-lang-hk:1.0.0-rc4'
    // 元游sdk越南语言包
    implementation 'io.github.yyxxgame.sdk:eyuancomm-lang-vn:1.0.0-rc4'

    // 华为渠道sdk
    implementation 'io.github.yyxxgame.sdk:eyuancomm-channel-lib-huawei:1.0.0-rc4'

    // oppo渠道sdk
    implementation 'io.github.yyxxgame.sdk:eyuancomm-channel-lib-huawei:1.0.0-rc4'

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);
        EYaunCommSdk.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	当前角色等级
rolePower	int	当前角色战力
roleGold	int	当前角色元宝
roleChange	int	当前角色累充金额（单位分）
roleCTime	long	当前角色创建的时间戳（10位），角色一旦创建则是固定值
vipLevel	string	当前Vip角色等级，若无传"none"
partyId	string	当前角色帮派Id，若无传"none"
partyName	string	当前角色帮派名称，若无传"none"

角色创建

    /**
     * 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)
    // 角色战力
    gameRoleInfo.setRolePower(100);
    // 角色元宝
    gameRoleInfo.setRoleGold(200);
    // 角色累充金额
    gameRoleInfo.setRoleChange(2000);
    // 帮派Id
    gameRoleInfo.setPartyId("1231");
    // 帮派名称
    gameRoleInfo.setPartyName("帮派1231")
    // 服务器ID
    gameRoleInfo.setServerId(serverId);
    // 服务器名
    gameRoleInfo.setServerName(serverName);
    // 用户VIP等级，无该字段则传空串"none"
    gameRoleInfo.setVipLevel("1");

    //角色创建
    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游戏打点上报（按需接入）

SDK埋点事件信息实体对象SdkEvent

参数	类型	说明
eventName	string	事件名称
eventParams	string	事件参数（预留）
standard	bool	是否fb标准事件
fbAliasName	string	fb标准事件名称，非标准事件则为""

    /**
     * 游戏内打点上报
     *
     * @param context Aontext上下文
     * @param sdkEvent SDK埋点事件信息实体对象
     */
    public void traceEvent(Context context, SdkEvent sdkEvent)

• 示例

    SdkEvent tutorialEvent = new SdkEvent();
    tutorialEvent.setEventName("tutorial");
    joinEvent.setStandard(false);
    EYuanCommSdk.getInstance().traceEvent(this, tutorialEvent);

    // fb标准事件
    SdkEvent joinEvent = new SdkEvent();
    joinEvent.setEventName("joinin_party");
    joinEvent.setStandard(true);
    joinEvent.setFbAliasName("fb_mobile_achievement_unlocked");
    EYuanCommSdk.getInstance().traceEvent(this, joinEvent);