LCM Android SDK 接入指南

当前版本RC9.6.1

此次的升级内容：

android 存储、读写权限收缩，会在需要时候提示授权，初始化时可以不申请权限直接初始化: LCMSDK.init()
地区码（海外-D商店）选择功能，需要后台配置数据

一、接入前准备

开发环境和前提步骤详见在L服务器上注册APP

二、SDK版本选择

RC9.6.1 Android LCMSDK 下载

三、Android Studio接入步骤

将zip解压后目录如下：

20190517 -----项目根目录

full                ——全功能（包含除纯google以外的所有商店的登录和支付）（测试用）

google         ——纯google商店的登录和支付（测试用）

Pickle          ——demo的主工程（测试用）

sdk              ——sdk的工程出包时使用这个（出包用）

facebook-sdk      ——facebook-sdk的工程是Facebook相关功能的基础库（出包用）
接入时如果需要测试自己登录和支付功能，请将根据接入的商店引用相应的工程。
- 引入规则：
- full ：是除纯google以外其他的商店（测试时也需要引入facebook-sdk）
- google ：纯google商店（测试时也需要引入facebook-sdk）
- sdk ：不含任何商店纯sdk
- facebook-sdk facebok基础库，用到facebook相关功能（包含登录，广告等）的包需要引入
- 注意：full，google，仅为测试时使用。出包上传打包工具时请引用【sdk】工程
- full，google，sdk 三个工程任选其一，不可同时引入，但出包时必须换成引用sdk----这点再次强调一下，facebook-sdk 使用到facebook相关功能（包含登录，广告等）时请引入此包。
demo的使用方法，可以直接使用Android Studio（版本最好越高越好，本demo使用的是3.2.1版本）打开项目即可。
接入时：将gradle.properties中的配置拷贝到自己工程的gradle.properties中（org.gradle.jvmargs 请使用demo中的配置。）
请将sample中的AndroidManifest.xml文件中application节点下注册的activity（除了SampleActivity）全部拷贝到自己的AndroidManifest.xml中，<uses-permission>权限也一样拷贝。
出包时必须引入的是sdk的工程，（facebook-sdk看需求引入：需要facebook登录，广告等功能时必须引入）其他的工程请勿引用（其他工程仅供测试时使用）。

在自己的build.gradle中引入sdk、full或者google工程就可以了，根据需求自行添加。
例如: 参考Demo的gradle导包即可，demo的gradle中有详细介绍。

配置需要注意的部分如下：
sourceSets中即!111!那行是针对繁体官网包过滤微信的类而配置，大陆官网包需要将这行代码注释掉。

dependencies多注意!nnn!所注释的内容描述。

sourceSets {
     main {
         manifest.srcFile 'AndroidManifest.xml'
         java.srcDirs = ['src']
         // !111! 当测试大陆官网包时，下面这行代码请注释掉
         java { exclude 'com/denachina/pickle/wxapi/**' }
         resources.srcDirs = ['src']
         aidl.srcDirs = ['src']
         renderscript.srcDirs = ['src']
         res.srcDirs = ['res']
         assets.srcDirs = ['assets']
         jniLibs.srcDirs = ['libs']
     }
}

dependencies {

    // 注意：以下三个工程3选一，
    //  但是出包的时候【必须】选择【sdk】，
    // 另外两个仅供接入时测试时使用，里面含sdk，不可同时使用

    // !555! 出包时必须导入sdk，上传打包工具时请务必只包含sdk。
    implementation project(':sdk')
     implementation project(':facebook-sdk')
    // 下面两个仅供调试时使用，仅提供登录和支付功能的测试，其他功能（推送、广告等）可通过打包工具打进去。
    // 下面两个工程已经包含sdk，请勿重复导入sdk！

    // !666! 测试 官网商店 时可以选择使用full，，含sdk
    // implementation project(':full')

    // !777! 测试 纯google商店 时可以选择google，含sdk
    // implementation project(':google')
}

四、Eclipse接入步骤

下面说明eclipse如何接入：

将zip解压后目录如下：

20190517 -----项目根目录

full                ——全功能（包含除纯google以外的所有商店的登录和支付）（测试用）

google         ——纯google商店的登录和支付（测试用）

Pickle          ——demo的主工程（测试用）

sdk              ——sdk的工程出包时使用这个（出包用）

facebook-sdk      ——facebook-sdk的工程是Facebook相关功能的基础库（出包用）
接入时如果需要测试自己登录和支付功能，请将根据接入的商店引用相应的工程。
- 引入规则：
- full ：是除纯google以外其他的商店（测试时也需要引入facebook-sdk）
- google ：纯google商店（测试时也需要引入facebook-sdk）
- sdk ：不含任何商店纯sdk
- facebook-sdk facebok基础库，用到facebook相关功能（包含登录，广告等）的包需要引入
- 注意：full，google，仅为测试时使用。出包上传打包工具时请引用【sdk】工程
- full，google，sdk 三个工程任选其一，不可同时引入，但出包时必须换成引用sdk----这点再次强调一下，facebook-sdk 使用到facebook相关功能（包含登录，广告等）时请引入此包。
demo的使用方法：直接用eclipse打开工程即可（例：直接打开： 20190517目录）。
接入时请根据自己的需求导入所需要的工程即可。请参考2
将samples目录下的Pickle中的AndroidManifest.xml文件中application节点下注册的activity（除了SampleActivity）全部拷贝到自己的AndroidManifest.xml中，<uses-permission>权限也一样拷贝。
出包时必须引入的是sdk的工程，（facebook-sdk看需求引入：需要facebook登录，广告等功能时必须引入）其他的工程请勿引用（其他工程仅供测试时使用）。

五、LCMSDK的接入

1. sdk的初始化接入流程

1）init()及权限申请

init()接口
在Activity的OnCreate()方法中进行初始化。

   // 1、传入两个基础参数，需要自己申请权限后调用（9.5.3后废弃）
    public static void init(Activity activity, EventHandler eventHandler);

    // 2、可传入权限集合初始化（9.5.3新增）
    public static void init(Activity activity, EventHandler eventHandler,
     Map<String, Boolean> permissions) ;

    // 3、可传入授权前提示框初始化（9.5.3新增）
    public static void init(Activity activity, EventHandler eventHandler,
     Dialog permissionDialog);

    // 4、可传入权限集合和授权前提示框初始化（9.5.3新增）
    public static void init(Activity activity, EventHandler eventHandler,
     Map<String, Boolean> permissions, Dialog permissionDialog);

授权前弹框（上架google的包需要，非必接，可根据需求接入)
- 新接入方式（9.5.3新增，推荐）

    // 这里传入permissionDialog，(google-play-store 上架的游戏/应用 用到)，可不接，传null即可 ，如2。
    Dialog permissionDialog = PermissionDefaultDialog.create(this,
     "权限提示", "应用将获取存储，电话等权限，以保证应用的正常运行！(语言适配由接入方实现)----测试专用",
      "知道了");
    LCMSDK.init(this, lcmEventHandler, permissionDialog);

    如果还需要额外的权限请参考<权限申请> 并使用init（）接口中的第四个接口接入。

权限申请
新方式接入（9.5.3新增，推荐）
权限申请可根据游戏需要的权限写入map即可。有三个权限是必须要的，sdk已经默认添加了，即为下面的三个权限。如果需要额外的权限，可新建 Map，将权限写入map 使用 init() 接口传入即可。
例如：

    /*
     Map中的key为游戏所需要的权限,value为true,表示该权限是必须权限，不可拒绝
     value为false 表示可拒绝权限，拒绝该权限后，不会弹提示框。相反则会重新弹出授权框
    */
    Map<String> map = new HashMap<>();
    map.put(Manifest.permission.READ_PHONE_STATE, true);
    map.put(Manifest.permission.WRITE_EXTERNAL_STORAGE, true);
    map.put(Manifest.permission.READ_EXTERNAL_STORAGE, true);
    LCMSDK.init(this, lcmEventHandler, map, permissionDialog);

    注： 以上3个权限sdk所必须的权限，可以参照此方式。
    如果没有额外需要申请的权限，第三个参数传入null即可（注意：不要使用两个参数的方法。）
     LCMSDK.init(this, lcmEventHandler, null , permissionDialog);

    扩展：即不需要额外权限，也不要授权前提示框的接入方式，3、4参数都传null即可。
    （注意：不要使用两个参数的方法。）
    LCMSDK.init(this, lcmEventHandler, null , null);

2）EventHandler回调

在初始化时需要传入EventHandler回调接口。具体处理下文有介绍，也可以参考Demo。EventHandler是LCMSDK的重要的一个监听器，它实现了游戏与LCMSDK的交互，包括登录，强更，公告等都是通过这个监听器回传给游戏的。

    // 创建接口回调对象。调用init接口需要传入。
    lcmEventHandler = new LCMSDK.EventHandler() {
        @Override
        public void onInitComplete(LCMInitializer lcmInitialization) {
            // 初始化完成
        }

        @Override
        public void onRemoteMessage(String message, String extras) {
            // 推送消息
        }

        @Override
        public void onSessionError(LCMError error) {
            // session错误回调
        }

        @Override
        public void onSessionUpdate(String accessToken, User user) {
            // session更新
        }

        @Override
        public void onUpdate(LCMUpdater updater) {
            // 强更
        }

        @Override
        public void onAnnouncement(LCMAnnouncement announcement) {
            // 公告
        }

        @Override
        public void onActivation(LCMActivation activation) {                // 激活码

        }

        @Override
        public void onLogoutComplete(String extra) {
            // 登出游戏成功
        }

        @Override
        public void onLoginComplete(String accessToken, User user) {
            // 登录游戏成功
        }

        @Override
        public void onQuitComplete(String extra) {
            // 退出
        }
    }

关于EventHandler接口的定义，可以参考 2.1 Android API
对EventHandler的详细说明：请看集成代码到自己的应用：6.实现最简单的EventHandler对象：

3）sdk生命周期绑定

LCMSDK需要与主Activity的生命周期保持一致，需要绑定主Activity的生命周期
相应的绑定如下：

LCMSDK中的方法 (参数)	Actiivty的生命周期
init(this,xx...) (此方法请参考上文介绍）	onCreate()
onResume(this)	onResume()
onPause(this)	onPause()
onStop(this)	onStop()
onReStart(this)	onReStart()
onDestory(this)	onDestory()
onActivityResult(this,requestCode, resultCode, data)	onActivityResult()
onNewIntent(this, intent)	onNewIntent()
onConfigurationChanged(this, newConfig)	onConfigurationChanged()
onRequestPermissionsResult(requestCode, permissions, grantResults)	onRequestPermissionsResult()
quit()	onBackPressed()

3）配置闪屏图片（Splash）

LCMSDK支持splash闪屏，在调用LCM init接口的时候，闪屏会出现，并在onInitComplete回调中消失。
不配置闪屏文件表示默认无闪屏。
游戏方若需要配置自己splash闪屏图片，则需要替换工程目录res/drawable-hdpi/lcm_splash_l.png和res/drawable-hdpi/lcm_splash_p.png两张图片，其中lcm_splash_l.png对应横屏游戏，lcm_splash_p.png对应竖屏游戏，有其一即可，游戏根据自己的横竖屏设置选择放入对应的闪屏图片。
注：闪屏图片是可以在资源文件中替换的，游戏的闪屏图片最好不要带有不可替换的内容，以至于在某些情况下该图片会被替换成其他图片，比如接入大陆渠道时，部分渠道方会要求使用渠道方的闪屏图片，则打包工具会将游戏自己的闪屏图片替换成渠道方的。

2. 配置文件appinfo.conf的配置说明

可参考Demo中res/raw目录下的appinfo.conf。

{"region":"ap","env":"live","sandbox":"false","appVersion":"1.0","productId":"pickle","storeType":"LCM_A_TW","md5":"LCM_A_TW"}

参数	说明
region	地区：大陆为cn ，海外为ap
env	游戏环境：配置live即可
sandbox	是否是沙箱环境：沙箱服为true，正式服为false
appVersion	游戏版本：例如：1.0
productId	为ope后台注册的应用名称
storeType	商店类型：大陆D商店为LCM_A_CN，台湾D商店为LCM_A_TW，GOOGLE和GOOGLE—D商店为GOOGLE，ONESTORE商店为ONESTORE, ONESTORE-D商店为ONESTORE2。可以参考Demo的配置。
md5	签名文件的md5，需在ope后台配置。

接入完成以后，运行验证: 在EventHandler中的onLoginComplete() 回调中获取accessToken即接入成功了（具体可见Demo）。

3. 登录、登出

1）登录接入

完成上述的基本配置以后登录的功能就接好了。
EventHandler的回调中有onLoginComplete(String accessToken, User user)回调，登录后需要一些处理可以在此方法中处理，比如登录后公告，需要在次回调中调用 LCMSDK.checkAnnouncement()进行处理。（可参考Demo）

2）登出接入

调用接口 LCMSDK.logout() 可实现登出功能
EventHandler的回调onLogoutComplete(String extra)中可做登出完成的一些处理，如:重新初始化登录界面:LCMSDK.login()。（可参考Demo）

4. 支付

1）支付接入流程

支付接入可参考：支付的接入
获取商品列表：

     VCBundle.getAsList(SampleActivity.this, new VCBundleCallback() {
            @Override
            public void onComplete(List<VCBundle> bundles, LCMError error) {
                if (error == null) {
                    // 获取到商品列表，游戏可以自己展示，处理。
                    vcBundleList = bundles;
                    // 检查订单，必接
                    LCMSDK.recover(SampleActivity.this, vcBundleList,
                            new LCMSDK.OnRepayListener() {
                                @Override
                                public void onComplete(String transactionId, JSONObject jo) {}

                                 @Override
                                public void onError(int errorCode, String errorMsg) {}
                    });
                } else {
                    //handle error.
                }
            }
     });

支付的使用方式
- 新增： VCBundle的接口，使用VCbundle对象调用buy()方法即可，此方式已经将实名制认证封装在里面。使用此方法可以省去实名制认证。

    vcBundle.buy(SampleActivity.this, purchaseMemo, new VCBundle.PurchaseCallback() {
         @Override
         public void onComplete(Wallet wallet, JSONObject payInfo, String memo, LCMError error) {
             // 后续处理见Demo
             doPurchase(vcBundle, wallet, parent, payInfo, error);
         }
    });

实名制认证
- 实名制认证只有大陆自营商店才有，应国家政策要求，国内必须接入，但不会影响到其他商店的支付接入。
- 请参考：实名制认证
Google商店支付
- 请参考：Google商店支付
DeNA自营商店大陆商店
请参考：DeNA自营商店
- 微信登录和支付：微信登录和支付
- 支付宝支付：支付宝支付
DeNA港澳台商店
请参考：DeNA港澳台商店
- MyCard支付： 3.1 MyCard支付
- PayPal支付： 3.2 PayPal支付
- MOL支付： 3.3 MOL支付
OneStore商店
- 请参考：OneStore商店

支付回调错误码说明

错误码（errorCode）	ErrorType	说明
200	`BANK_CREATE_ORDER_ERROR`	创建订单错误
205	`BANK_PURCHASE_FAILURE`	购买失败
206	`BANK_PURCHASE_CANCEL`	购买取消
216	`BANK_PURCHASE_RESULT_UNKNOWN`	购买结果未知
217	`BANK_GET_CURRENT_BALANCE_ERROR`	获取当前余额失败
218	`BANK_GET_BALANCE_INFO_ERROR`	获取余额信息失败
220	`BANK_PURCHASE_NO_GOOGLE_ACCOUNT`	购买失败 no google account
222	`BANK_REPAY_ERROR`	重新购买失败
299	`BANK_NOTIFY_ERROR`	通知服务端失败
- 更多详见附录.

5. 公告

1）公告接入流程

公告是在EventHandler的onAnnouncement(LCMAnnouncement announcement)中做处理的。
如果游戏不需要自定义UI可使用：

     announcement.applyDefault(new LCMAnnouncement.DefaultAnnouncementCallBack() {
             @Override
             public void callback() {
                // 执行正常进入游戏的逻辑，祥见pickle，SampleActivity.java.
                sampleStartToLoginToGame();
             }
});

如果游戏需要自定义UI，需要接入者手动调用 announcement.continueProcessing();
只有调用了此方法LCMSDK才会继续登录流程，但是该方法不能滥用，介入者需自行判断使用时机。
例如：在自己写的弹窗的确定按钮点击事件中调用此方法。

6. 推送

1）推送接入流程

推送分为大陆商店的推送（百度推送）和Google的推送（FCM推送）
推送在EventHandler的回调方法是onRemoteMessage(String message, String extras)
游戏可根据需求自行处理。
百度推送接入: 请参考百度推送文档
Google推送接入: 请参考 FCM推送文档
信鸽推送接入：详见信鸽官方文挡（https://xg.qq.com/docs/android_access/xg_push_introduction.html）
信鸽推送集成步骤：
1、前往信鸽管理台（https://xg.qq.com/)，使用QQ号码登陆，进入应用注册页，填写“应用名称”和“应用包名”（必须要跟APP一致），选择“操作系统”和“分类”，最后点击“创建应用”。应用创建成功后，点击“应用配置”即可看到 APP 专属的 AccessId 和 AccessKey 等信息。
2、前往华为开放平台（http://developer.huawei.com/）详细步骤参考（https://xg.qq.com/docs/android_access/huawei_push.html）注册，创建应用，得到appId和AppSecret。(配置到信鸽管理后台海外厂商通道中)
3、前往小米开放平台（https://dev.mi.com/console/appservice/push.html），详细步骤参考（https://xg.qq.com/docs/android_access/mi_push.html）注册，创建应用，得到appId和appKey，和appSecret。(配置到信鸽管理后台海外厂商通道中)
4、前往魅族推送官网（https://open.flyme.cn/open-web/views/push.html），详细步骤参考（https://xg.qq.com/docs/android_access/meizu_push.html）注册，创建应用，得到appId和appKey，和appSecret。(配置到信鸽管理后台海外厂商通道中)
5、经过上诉的步骤所得的小米和魅族的appid和appkey需要配置到ope后台上。
6、经过以上配置就可以了。

7. 强更

1）强更接入流程

强更会在EventHandler中的onUpdate(LCMUpdater updater)回调给游戏
可参考Demo中的处理，Demo中使用默认处理

        @Override
            public void onUpdate(LCMUpdater updater) {
                //TODO 强制更新回调这里（推荐自定义UI接入方式）(必接)
                /* 游戏收到该回调后可通过显示LCM默认强更UI或者自定义强更页面，
                如果需要设置下载路径可通过 ：
                updater.setTargetFilePath("/sdcard/dwonload/xxx.apk")
                */
                updater.showDefaultUI();
            }

详细介绍请参考：强制更新

8. onSessionError处理

游戏研发需要在回调函数onSessionError判断错误码类型，展示对应的错误信息弹窗。

错误码（errorCode）	LCMError.ErrorType	说明
108	`AUTH_SESSION_OCCUPIED`	异地登录，账号在另一台设备上登录了，挤掉线
116	`AUTH_USER_FREEZE_TEMPORARY`	临时冻结账户
117	`AUTH_USER_FREEZE_PERMANENT`	永久冻结账户
119	`AUTH_CREDENTIAL_NO_GOOGLE_ACCOUNT`	谷歌账号未登录处理(针对海外包，大陆包忽略)
409	`BIND_ACCOUNT_ERROR`	绑定账号错误，该facebook/line账号已经被link过，请换一个facebook/line账号进行link.（针对海外包，大陆包忽略）

详情请参考Demo。

9. 游戏打点事件（创角事件）

1）游戏打点接入流程

详情请参考：游戏打点事件

10. 悬浮窗(DeNA自营商店商店接入需要）

1）悬浮窗接入

配置悬浮框的默认显示位置
0：左上角
- 1：右上角
- 2：左下角
- 3：右下角
- -1:则不显示悬浮框
- 默认显示 0：左上角

在清单文件中配置

<meta-data android:name="menubar_default_position" android:value="0"/>

2）全面屏、刘海屏适配配置

为了悬浮窗能够适配刘海屏和全面屏，游戏可以配置以下属性到application节点下

全面屏适配可以参考pickle中的代码，用于适配9.0的刘海屏

final View decorView = getWindow().getDecorView();
decorView.post(new Runnable() {
    @Override
    public void run() {
        // 9.0 api 刘海屏适配，允许使用刘海品区域
        if (Build.VERSION.SDK_INT >= 28) {
            WindowInsets rootWindowInsets = decorView.getRootWindowInsets();
            if (rootWindowInsets != null) {
                DisplayCutout cutout = rootWindowInsets.getDisplayCutout();
                if (cutout != null) {
                    LCMLog.d("有刘海");
                    WindowManager.LayoutParams lp = getWindow().getAttributes();
                    lp.layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES;
                    getWindow().setAttributes(lp);
                }
            }
        }
    }
});

mainfest中的配置

<!--适配全面屏 start-->
<meta-data
    android:name="android.max_aspect"
    android:value="2.4" />
<!--华为刘海区域使用配置-->
<meta-data
    android:name="android.notch_support"
    android:value="true" />
<!--小米刘海区域使用配置-->
<meta-data
    android:name="notch.config"
    android:value="portrait|landscape" />
<!--VIVO刘海区域使用配置-->
<meta-data
    android:name="android.vendor.full_screen"
    android:value="true" />
<!--适配全面屏 end-->

11.其他（非必接）

1）本地推送

请参考：本地推送

2）激活码

请参考：激活码

12. 出包

出包改动比较大，无需参考原来的出包方式：最新的出包方式非常简单，首先确保自己引入的工程是sdk工程，确保自己的程序运行出的app不出现闪退崩溃等情况，然后直接打出apk包上传至打包工具即可。无需其他操作。
注：960无需参考此！老的出包方式，请参考：LCM9.5.0及以上出包指南

13. 常见问题-FAQ

Q：无法正常登陆游戏？
A：检查appinfo.conf配置文件的storeType和md5是否配置正确。

14. 联系方式

技术QQ群：878394398
邮箱：sdk-app_cn@dena.jp

版本:RC9.6.0
日期：2019.5.17

15. 附录

错误码附录

错误码（errorCode）	LCMError.ErrorType	说明
100	`AUTH_STORE_CREDENTIAL_ERROR`	Get store credential error
101	`AUTH_STORE_TYPE_ERROR`	StoreType 错误
102	`AUTH_SESSION_ERROR`	创建session错误
103	`AUTH_SOCIAL_ACCOUNT_ERROR`	Get social account error
104	`AUTH_STORE_ACCOUNT_ERROR`	获取商店账号错误
105	`AUTH_GET_LINK_INFO_ERROR`	获取绑定信息错误
106	`AUTH_LINK_ACCOUNT_ERROR`	绑定账号错误
107	`AUTH_LOAD_ACCOUNT_ERROR`	加载账号错误
108	`AUTH_SESSION_OCCUPIED`	异地登录，账号在另一台设备上登录了，挤掉线
111	`AUTH_UNLINK_ACCOUNT_ERROR`	Unlink account error
112	`AUTH_GET_ALL_USER_IDS_ERROR`	Get all user ids error
113	`AUTH_RESET_USER_ERROR`	Reset user error，重置用户错误
114	`AUTH_SWITCH_USER_ERROR`	Switch user error，切换用户错误
116	`AUTH_USER_FREEZE_TEMPORARY`	临时冻结账户
117	`AUTH_USER_FREEZE_PERMANENT`	永久冻结账户
119	`AUTH_CREDENTIAL_NO_GOOGLE_ACCOUNT`	谷歌账号未登录处理
200	`BANK_CREATE_ORDER_ERROR`	创建订单错误
205	`BANK_PURCHASE_FAILURE`	购买失败
206	`BANK_PURCHASE_CANCEL`	购买取消
216	`BANK_PURCHASE_RESULT_UNKNOWN`	购买结果未知
217	`BANK_GET_CURRENT_BALANCE_ERROR`	获取当前余额失败
218	`BANK_GET_BALANCE_INFO_ERROR`	获取余额信息失败
220	`BANK_PURCHASE_NO_GOOGLE_ACCOUNT`	购买失败 no google account
222	`BANK_REPAY_ERROR`	重新购买失败
299	`BANK_NOTIFY_ERROR`	通知服务端失败
901	`PARAMETER_ERROR`	参数错误
903	`LCM_NETWORK_ERROR`	网络异常
409	`BIND_ACCOUNT_ERROR`	绑定账号错误，该facebook/line账号已经被link过，请换一个facebook/line账号进行link.
411	`BIND_ACCOUNT_FREQUENT_ERROR`	绑定账号太频繁，每个月只能绑定一次