更新接入文档

README.md

@@ -1,3 +1,612 @@
-# EYuanCommDemo
+[TOC]
 
-元游海外融合SDK demo
+# 修订记录
+
+| 日期         | 版本    | 说明   | 作者  |
+|:----------:|:-----:|:---- |:---:|
+| 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`**中设置
+  
+  ```properties
+  android.useAndroidX=true
+  android.enableJetifier=true
+  ```
+
+- 请务必使用我们提供的keystore签名文件进行签名，否则SDK功能会异常
+
+- [服务端接口文档](http://yydocs.yyxxgame.com/web/#/147/892)
+
+- [客户端SDK接入Demo](http://gogs.yyxxgame.com/Client/EYuanCommSdkDemo)
+
+# 2.SDK资源接入说明
+
+- 1.接入中存在问题请参考SDK提供的Demo工程或联系技术解决
+
+- 2.拷贝对应渠道目录下**`assets`**至项目中
+
+- 3.拷贝对应渠道目录下**`res/values/strings.xml`**中的内容至项目中相应的文档中，如果没有strings.xml则新建一份即可，如果该目录没有则不需要处理
+
+- 4.在应用**`build.gradle`**中**`dependencies`**节点下添加SDK依赖，目前只提供远程依赖
+  
+  > 在项目级**`build.gradle`**文件下的**`allprojects`**节点下添加仓库的url
+  
+  ```groovy
+      allprojects {
+          repositories {
+              ...
+              mavenCentral()
+              // 华为sdk仓库
+              maven { url 'https://developer.huawei.com/repo' }
+              ...
+          }
+      }
+  ```
+  
+  > 在应用级**`build.gradle`**文件下的**`allprojects`**节点下添加仓库的url
+  
+  ```groovy
+    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.接口说明
+
+> <font color=red size=5>**SDK的所有接口如无特殊说明，默认均为必接且请务必在游戏主线程调用**</font>
+
+## 1）同步Application中的生命周期
+
+- 若游戏无自定义Application则直接在清单文件AndroidManifest.xml的**``application``**节点中设置name属性为SDK提供的Application**``cn.yyxx.eyuangame.base.EYuanCommApplication``**
+
+```xml
+    <application android:name="cn.yyxx.eyuangame.base.EYuanCommApplication">
+        ···
+    </application>
+```
+
+- 若游戏有自定义Application，则需要继承SDK提供的Application
+
+```java
+    public class DemoApplication extends EYuanCommApplication {
+        @Override
+        protected void attachBaseContext(Context base) {
+            super.attachBaseContext(base);
+        }
+
+        @Override
+        public void onCreate() {
+            super.onCreate();
+        }
+    }
+```
+
+## 2）同步游戏Activity中各个生命周期至SDK
+
+- 同步onStart
+
+```java
+    @Override
+    protected void onStart() {
+        super.onStart();
+        EYuanCommSdk.getInstance().onStart(this);
+    }
+```
+
+- 同步onResume
+
+```java
+    @Override
+    protected void onResume() {
+        super.onResume();
+        EYuanCommSdk.getInstance().onResume(this);
+    }
+```
+
+- 同步onRestart
+
+```java
+    @Override
+    protected void onRestart() {
+        super.onRestart();
+        EYuanCommSdk.getInstance().onReStart(this);
+    }
+```
+
+- 同步onPause
+
+```java
+    @Override
+    protected void onPause() {
+        super.onPause();
+        EYuanCommSdk.getInstance().onPause(this);
+    }
+```
+
+- 同步onStop
+
+```java
+    @Override
+    protected void onStop() {
+        super.onStop();
+        EYuanCommSdk.getInstance().onStop(this);
+    }
+```
+
+- 同步onDestroy
+
+```java
+    @Override
+    protected void onDestroy() {
+        super.onDestroy();
+        EYuanCommSdk.getInstance().onDestroy(this);
+    }
+```
+
+- 同步onActivityResult
+
+```java
+    @Override
+    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+        super.onActivityResult(requestCode, resultCode, data);
+        EYuanCommSdk.getInstance().onActivityResult(this, requestCode, requestCode, data);
+    }
+```
+
+- 同步onNewIntent
+
+```java
+    @Override
+    protected void onNewIntent(Intent intent) {
+        super.onNewIntent(intent);
+        EYuanGame.getInstance().onNewIntent(this, intent);
+    }
+```
+
+## 3）SDK通用回调接口ICallback说明
+
+```java
+    public interface ICallback {
+        void onResult(int code, String result);
+    }
+```
+
+| 参数     | 类型     | 说明            |
+|:------:|:------:|:-------------:|
+| code   | int    | 状态码（0成功，-1失败） |
+| result | string | 返回信息          |
+
+## 4）SDK初始化
+
+- 在游戏的主Activity的onCreate中调用
+
+```java
+    /**
+     * SDK初始化
+     *
+     * @param activity    Activity上下文
+     * @param isLandscape 是否横屏
+     * @param callback    SDK初始化回调
+     */
+    public void initialize(final Activity activity, final Boolean isLandscape, ICallback callback)
+```
+
+- 示例
+
+```java
+    @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）用户账号登录
+
+```java
+    /**
+     * 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  |
+
+- 示例
+
+```java
+    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）用户账号登出
+
+> 用户在游戏中触发登出，游戏回到选服界面重新拉起登录
+
+```java
+    /**
+     * SDK用户登出账号
+     *
+     * @param activity Activity上下文
+     * @param callback 登出回调对象
+     */
+    public void logout(Activity activity, ICallback callback)
+```
+
+- 示例
+
+```java
+    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）                |
+
+> 角色创建
+
+```java
+    /**
+     * SDK角色创建信息上报
+     *
+     * @param activity Activity上下文
+     * @param roleInfo 角色信息实体
+     */
+    public void roleCreate(Activity activity, SdkRoleInfo roleInfo)
+```
+
+> 角色进入服务器（角色登录）
+
+```java
+    /**
+     * SDK角色登录信息上报
+     *
+     * @param activity Activity上下文
+     * @param roleInfo 角色信息实体
+     */
+    public void roleLauncher(Activity activity, SdkRoleInfo roleInfo)
+```
+
+> 角色升级
+
+```java
+    /**
+     * SDK角色升级信息上报
+     *
+     * @param activity Activity上下文
+     * @param roleInfo 角色信息实体
+     */
+    public void roleUpgrade(Activity activity, SdkRoleInfo roleInfo)
+```
+
+- 示例
+
+```java
+    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）支付储值
+
+> 请务必保证调用角色信息上报中的角色登录上报后再调用
+> <font color=red size=5>**客户端SDK回调的只是支付流程的结果，实际支付结果将由服务端回调**</font>
+> 默认情况均为内购包即上架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 | 支付签名，具体签名规则详见服务端接口文档 |
+
+```java
+    /**
+     * SDK用户支付
+     *
+     * @param activity   Activity上下文
+     * @param chargeInfo 支付信息实体对象
+     * @param isIab             是否内购
+     * @param callback   支付回调对象
+     */
+    public void charge(Activity activity, SdkChargeInfo chargeInfo, boolean isIab , ICallback callback)
+```
+
+- 示例
+
+```java
+    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则显示游戏原生退出框即可
+
+```java
+    /**
+     * 显示退出框
+     *
+     * @param activity Activity上下文
+     * @param callback 退出回调对象
+     */
+    public boolean hasExitView(Activity activity)
+```
+
+```java
+    /**
+     * 显示退出框
+     *
+     * @param activity Activity上下文
+     * @param callback 退出回调对象
+     */
+    public void openExitView(Activity activity, ICallback callback)
+```
+
+- 示例
+
+```java
+    //重写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初始化成功后设置浮标切换用户监听
+
+```java
+    /**
+     * 设置SDK浮标切换用户监听
+     *
+     * @param callback 切换用户回调对象
+     */
+    public void setOnFloatBallLogout(ICallback callback)
+```
+
+- 示例
+
+```java
+    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（选接）
+
+```java
+    /**
+     * 获取当前SDK版本
+     *
+     * @return
+     */
+    public String getCurrentUserId()
+```
+
+- 示例
+
+```java
+    EYuanCommSdk.getInstance().getCurrentUserId();
+```
+
+## 12）获取SDK当前版本（选接）
+
+```java
+    /**
+     * 获取当前SDK版本
+     *
+     * @return
+     */
+    public String getCurrentSdkVersion()
+```
+
+- 示例
+
+```java
+    EYuanGame.getInstance().getCurrentSdkVersion();
+```
+
+## 13）SDK日志接口（选接）
+
+> 若游戏有需要持久化java、kotlin和C++(联系我方技术获取头文件)层的日志，可以使用SDK的日志接口。SDK的日志框架底层使用C++进行开发，使用了Linux系统的mmap内存拷贝技术
+> SDK会默认缓存3天的日志，过期则自动删除
+> 缓存的文件使用Facebook开源的压缩算法zlib进行压缩
+> 缓存路径为**手机内部存储目录/Android/data/包名/files/dolin/zap**，即应用的私有目录
+> 更多使用方法请联系我方技术
+
+```java
+    // debug日志
+    Logger.d(TAG,msg);
+    // info日志
+    Logger.i(TAG,msg);
+    // error日志
+    Logger.e(TAG,msg);
+```