Android SDK 接入

1. 概述

官网下载SDK后进行解压,解压后包含：

2. 前期准备

2.1 准备工作

如果应用开启了手机号认证服务，请确保终端设备已经开启4G网络（联通、移动支持3G网络，但接口耗时会增加），手机号认证授权之后，联通电信可立即使用，移动需等待10分钟后使用。

2.2 运行demo工程

解压Android Demo工程，需要将包名、applicationId、应用密钥、服务密钥（手机号认证）修改为正确的值。

2.3 搭建开发环境

应用必须运行在Android 4.1+平台上。

2.3.1 导入aar

将下载SDK拷贝到项目libs目录下

2.3.2 添加依赖

2.3.3 混淆忽略

若开启资源混淆，需要配置

# etas 对外提供的类不被混淆
-keep public class com.esandinfo.etas.ETASManager** { *; }
-keep public class com.esandinfo.etas.EtasResult** { *; }
-keep public class com.esandinfo.etas.IfaaBaseInfo {*;}
-keep public class com.esandinfo.etas.IfaaBaseInfo$* {*;}
-keep public class com.esandinfo.etas.IfaaCommon {*;}
-keep public class com.esandinfo.etas.IfaaCommon$* {*;}
-keep public class com.esandinfo.etas.model.json.** {*;}
-keep public class com.esandinfo.etas.biz.** {*;}
-keep public class com.esandinfo.etas.IfaaRequestBaseInfo {*;}
-keep public class com.esandinfo.etas.callback.** {*;}
-keep public class com.esandinfo.etas.utils.IfaaClient {*;}
# ifaa 原始接⼝不被混淆
-keep class org.ifaa.** {*;}
# 保留所有的本地native⽅法不被混淆
-keepclasseswithmembernames class * {
native <methods>;
}
#号码认证配置
-keep public class  R.drawable.authsdk*
-keep public class  R.layout.authsdk*
-keep public class  R.anim.authsdk*
-keep public class  R.id.authsdk*
-keep public class  R.string.authsdk*
-keep public class  R.style.authsdk*
#SDK不被混淆
-keep class com.idsmanager.doraemonlibrary.** {*;}

2.3.4 权限添加

<uses-permission android:name="android.permission.INTERNET" />   <!--网络权限-->
<uses-permission android:name="android.permission.USE_FINGERPRINT" />   <!--指纹权限-->
    <uses-permission android:name="android.permission.MANAGE_FINGERPRINT" tools:ignore="ProtectedPermissions"/>  <!--指纹管理权限-->
<uses-permission android:name="cn.org.ifaa.permission.USE_IFAA_MANAGER" />    <!--⼈脸权限-->
<uses-permission android:name="android.permission.USE_FACERECOGNITION" />
<uses-permission android:name="oppo.permission.USE_FACE" /> <!--个别⼚商⼈脸权限-->
<uses-permission android:name="android.permission.CAMERA" /><!--相机权限，需要⽤户进⾏授权-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- 检查wifi网络状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- 检查网络状态 -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <!-- 切换网络通道 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!-- 本地信息缓存 -->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> <!-- 开关Wi-Fi状态，解决中国机型移动网络权限问题需要 -->

2.3.5 网络权限配置

修改AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.idsmanager.doraemondemoactivity">

...

  <application
       ...
        android:networkSecurityConfig="@xml/network_security_config"
       >
       ...

</manifest>

在res目录下创建xml目录以及network_security_config.xml文件

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
    <domain-config cleartextTrafficPermitted="true" >
        <domain includeSubdomains="true">enrichgw.10010.com</domain> <!-- 联通内部5G请求域名，开发者需要添加 -->
        <domain includeSubdomains="true">onekey.cmpassport.com</domain>  <!-- 移动内部请求域名，开发者需要添加 -->

    </domain-config>
</network-security-config>

添加Activity 声明

在AndroidManifest.xml添加Activity声明

        <!--联通电信授权页-->
        <!--如果不需要使用窗口模式，不要使用authsdk_activity_dialog主题，会出现异常动画-->
        <!--如果需要使用authsdk_activity_dialog主题，则screenOrientation一定不能指定明确的方向，
            比如portrait、sensorPortrait，在8.0的系统上不允许窗口模式指定orientation，会发生Crash，需要指定为behind，
            然后在授权页的前一个页面指定具体的orientation-->
        <!--  使用弹窗模式必须添加。-->
        <activity
            android:name="com.mobile.auth.gatewayauth.LoginAuthActivity"
            android:configChanges="orientation|keyboardHidden|screenSize"
            android:exported="false"
            android:launchMode="singleTop"
            android:theme="@style/authsdk_activity_dialog" />
        <!--二次弹窗界面-->
        <activity
            android:name="com.mobile.auth.gatewayauth.PrivacyDialogActivity"
            android:configChanges="orientation|keyboardHidden|screenSize"
            android:exported="false"
            android:launchMode="singleTop"
            android:screenOrientation="behind"
            android:theme="@style/authsdk_activity_dialog" />
        <!--协议页面webview-->
        <activity
            android:name="com.mobile.auth.gatewayauth.activity.AuthWebVeiwActivity"
            android:configChanges="orientation|keyboardHidden|screenSize"
            android:exported="false"
            android:launchMode="singleTop"
            android:screenOrientation="behind" />
    

2.3.6 Support 包

使用v4包com.android.support:support-v4版本高于25.4.0，或者v7包com.android.support:appcompat-v7版本高于25.4.0.

2.3.7 获取app md5 签名值

使用Android studio gradle，点击signingReport，得到MD5签名值，将冒号去掉并转小写。

3. SDK 调用说明

需要在APP中集成安全认证客户端SDK，并在服务端完成API对接。应用密钥和服务密钥获取请查看应用管理。

4. 手机号认证SDK方法说明

4.1 主类DoraemonManager介绍

4.1.1 初始化

此接口需要开发者调用服务端SDK的获取应用授权Token接口,自定义回调函数，然后通过FetchAccessTokenCallBackImpl回传给移动端SDK

/**
  * 初始化SDK
  *
  * @param context 系统上下文
  */
DoraemonManager.init(context, this.app_external_id_text.getText().toString(), this.app_key.getText().toString(), new FetchAccessTokenCallBackImpl(), new DoraemonCallback() {
   @Override
   public void onFailure(Exception e) {
       Log.e(TAG, "DoraemonManager init faild", e);
       MainActivity.this.showToast("SDK初始化失败！" + e.getMessage());
   }

   @Override
   public void onSuccess(Object data) {
       Log.e(TAG, "DoraemonManager init success");
       MainActivity.this.showToast("SDK初始化成功！");
   }
});

FetchAccessTokenCallBackImpl 需要获取AccessToken后返回给SDK，示例如下

public class FetchAccessTokenCallBackImpl implements FetchAccessTokenCallBack {
    private static final String TAG = FetchAccessTokenCallBackImpl.class.getSimpleName();

    /**
     * 获取AccessToken回调方法
     *
     * @return
     */
    @Override
    public AccessTokenInfoResult fetchAccessToken(FetchAccessTokenRequest fetchAccessTokenRequest) {
        AccessTokenInfoResult callbackResult = new AccessTokenInfoResult();
        try {
            //参照准备工作接入
        } catch (Exception e) {
            Log.e(TAG, "getAccessTokenRun exception", e);
            callbackResult.setSuccess(false);
            callbackResult.setMessage(e.getMessage());
        }
        return callbackResult;
    }
}

4.1.2 本机手机号码一键登录

 /**
   * 手机号码一键登录
   *
   * @param activity
   * @param doraemonCallback 回调接口
   * @param authUIConfig     定制UI
   */
DoraemonManager.phoneNumberLogin(this, new DoraemonCallback() {
    @Override
    public void onFailure(Exception e) {
        Log.e(TAG, "phoneNumberLogin faild", e);
        MainActivity.this.showToast("手机号登录失败！" + e.getMessage());
    }

    @Override
    public void onSuccess(Object data) {
         Log.e(TAG, "DoraemonManager init success");
         MainActivity.this.showToast("手机号码登录成功！" + data);
     }
}, baseUIConfig);

一键登录页面定制类，示例如下

public class FullPortConfig extends BaseUIConfig {
    private final String TAG = "全屏竖屏样式";

    public FullPortConfig(Activity activity) {
        super(activity);
    }


    @Override
    public void configAuthPage(PhoneNumberAuthHelper mAuthHelper) {
        mAuthHelper.setUIClickListener(new AuthUIControlClickListener() {
            @Override
            public void onClick(String code, Context context, String jsonString) {
                JSONObject jsonObj = null;
                try {
                    if (!TextUtils.isEmpty(jsonString)) {
                        jsonObj = new JSONObject(jsonString);
                    }
                } catch (JSONException e) {
                    jsonObj = new JSONObject();
                }
                switch (code) {
                    //点击授权页默认样式的返回按钮
                    case ResultCode.CODE_ERROR_USER_CANCEL:
                        Log.e(TAG, "点击了授权页默认返回按钮");
                        mAuthHelper.quitLoginPage();
                        mActivity.finish();
                        break;
                    //点击授权页默认样式的切换其他登录方式，会关闭授权页
                   case ResultCode.CODE_ERROR_USER_SWITCH:
                        Log.e(TAG, "点击了授权页默认切换其他登录方式");
                        break;
                    //点击一键登录按钮会发出此回调
                    //当协议栏没有勾选时，点击按钮会有默认toast 如果不需要或者希望自定义内容 setLogBtnToastHidden(true)隐藏默认Toast
                    //通过此回调自己设置toast
                    case ResultCode.CODE_ERROR_USER_LOGIN_BTN:
                        if (!jsonObj.optBoolean("isChecked")) {
                            Toast.makeText(mContext, "isCheck", Toast.LENGTH_SHORT).show();
                        }
                        break;
                    //checkbox状态改变触发此回调
                    case ResultCode.CODE_ERROR_USER_CHECKBOX:
                        Log.e(TAG, "checkbox状态变为" + jsonObj.optBoolean("isChecked"));
                        break;
                    //点击协议栏触发此回调
                    case ResultCode.CODE_ERROR_USER_PROTOCOL_CONTROL:
                        Log.e(TAG, "点击协议，" + "name: " + jsonObj.optString("name") + ", url: " + jsonObj.optString("url"));
                        break;
                    default:
                        break;

                }

            }
        });
        mAuthHelper.removeAuthRegisterXmlConfig();
        mAuthHelper.removeAuthRegisterViewConfig();
        //添加自定义切换其他登录方式
        mAuthHelper.addAuthRegistViewConfig("switch_msg", new AuthRegisterViewConfig.Builder()
                .setView(initSwitchView(350))
                .setRootViewId(AuthRegisterViewConfig.RootViewId.ROOT_VIEW_ID_BODY)
                .setCustomInterface(new CustomInterface() {
                    @Override
                    public void onClick(Context context) {
                        Toast.makeText(mContext, "切换到短信登录方式1", Toast.LENGTH_SHORT).show();

                        mAuthHelper.quitLoginPage();
                    }
                }).build());
        int authPageOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT;
        if (Build.VERSION.SDK_INT == 26) {
            authPageOrientation = ActivityInfo.SCREEN_ORIENTATION_BEHIND;
        }
        mAuthHelper.setAuthUIConfig(new AuthUIConfig.Builder()
                .setAppPrivacyOne("《自定义隐私协议》", "https://****/user")
                .setAppPrivacyTwo("《》", "https://***")
                .setAppPrivacyColor(Color.GRAY, Color.parseColor("#002E00"))
                //隐藏默认切换其他登录方式
                .setSwitchAccHidden(true)
                //隐藏默认Toast
                .setLogBtnToastHidden(true)
                //沉浸式状态栏
                .setNavColor(Color.parseColor("#026ED2"))
                .setStatusBarColor(Color.parseColor("#026ED2"))
                .setWebViewStatusBarColor(Color.parseColor("#026ED2"))


                .setLightColor(false)
                .setWebNavTextSizeDp(20)
                //图片或者xml的传参方式为不包含后缀名的全称，需要文件需要放在drawable或drawable-xxx目录下 in_activity.xml, mytel_app_launcher.png
                .setAuthPageActIn("in_activity", "out_activity")
                .setAuthPageActOut("in_activity", "out_activity")
                .setVendorPrivacyPrefix("《")
                .setVendorPrivacySuffix("》")
                .setPageBackgroundPath("page_background_color")
                .setLogoImgPath("mytel_app_launcher")
                //一键登录按钮三种状态背景示例login_btn_bg.xml
                .setLogBtnBackgroundPath("login_btn_bg")
                .setScreenOrientation(authPageOrientation)
                .create());
    }

4.1.3 检查本机是否支持一键登录

/**
  * 检查本机是否支持一键登录
  * @param i
  * @param doraemonCallback
  */
DoraemonManager.checkEnvAvailable(PhoneNumberAuthHelper.SERVICE_TYPE_LOGIN, new DoraemonCallback() {
     @Override
     public void onFailure(Exception e) {
         Log.e(TAG, "phoneNumberLogin faild", e);
         MainActivity.this.showToast("checkEnvAvailable失败！" + e.getMessage());
     }

     @Override
     public void onSuccess(Object data) {
         Log.e(TAG, "DoraemonManager init success");
         MainActivity.this.showToast("checkEnvAvailable成功！" + data);
     }
});

4.1.4 退出一键号码登录页

DoraemonManager.quitLoginPage();

4.2 手机号码验证

用户输入手机号码，验证是否是本机手机号

/**
  * 手机号码验证
  *
  * @param phoneNumber      手机号码
  * @param doraemonCallback 回调接口
  */
DoraemonManager.phoneNumberVerify(phoneNum, new DoraemonCallback() {
     @Override
     public void onFailure(Exception e) {
         Log.e(TAG, "phoneNumberLogin faild", e);
         MainActivity.this.showToast("手机号认证失败！" + e.getMessage());
     }

     @Override
     public void onSuccess(Object data) {
         Log.e(TAG, "DoraemonManager init success");
         MainActivity.this.showToast("手机号码认证成功！" + data);
     }
});

4.3 校验JwtToken

最后需要校验JwtToken来确保此次认证结果真实有效。

5. 手机号码认证授权页面说明

5.1 授权页面设计规范

5.2 弹窗授权页面设计规范（支持横竖屏，以竖屏示意）

6. 常见问题

1.首次取号时，为什么APP网络通信正常，手机号认证一直失败？

2.checkEnvAvailable函数返回false？

3. 获取token失败，一般有哪些原因？

• 手机设置检测网络制式，中国移动支持2G/3G/4G、中国联通支持3G/4G、中国电信支持4G，但各大运营商网络在4G网络成功率较高

• 接口超时时间是否过短，建议3000~5000ms

• SIM能否欠费，是否可以蜂窝网络上网。

• 切换卡的过程中，需要等网络稳定后，再使用认证登录功能。

4.Android双卡手机本机号码登录过程中，本机号码登录逻辑是怎么样的？

5.返回错误码600005，手机终端不安全有哪些原因？

6.权限问题

若出现权限相关问题，请检查 APP的权限是否申请正常。正常引用 aar，权限会自动 merge。若权限没有 merge，需要添加如下权限。

<uses-permission
    android:name="android.permission.INTERNET" />
<uses-permission
    android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission
    android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission
    android:name="android.permission.CHANGE_NETWORK_STATE" />

7. 非法手机号码

部分试点纯流量卡，未实名的手机号码会返回非法手机号码的情况。

8. VPN报错

用户开启VPN后使用SDK进行本机号码登录的时候，联通号码会出现源IP错误，电信号码会出现800008错误，移动号码会出现103111错误。请关闭VPN或者打开飞行模式再关闭后进行重试。

9. 页面非法修改

添加悬浮窗控件遮挡隐私协议、登录按钮以及掩码，或者将字体颜色设置为透明，sdk回调600005页面非法修改。

10. 当使用移动卡请求本机号码登录不成功，出现以下报错信息时：

ontokenfaild{"code":"600011","msg":"vendorCode:200025, msg:获得的手机授权码失败：{\"resultCode\":\"200025\",\"authType\":\"1\",\"authTypeDes\":\"WIFI下网关鉴权\",\"resultDesc\":\"发生未知错误\"}","requestCode":0,"vendorName":"CMCC"}请检查依赖v4包com.android.support:support-v4版本是否高于25.4.0或者v7包com.android.support:appcompat-v7版本是否高于25.4.0。

11. 当使用移动卡请求本机号码登录不成功，出现以下报错信息时

ontokenfaild{"code":"600011","msg":"vendorCode:200028, msg:获得的手机授权码失败：{\"resultCode\":\"200028\”,\”authType\":\"1\",\"authTypeDes\”:\”网络鉴权\",\"resultDesc\”:\”网络异常\”}”,”requestCode":0,"vendorName":"CMCC"}

<application
        android:name=".DemoApplication"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/config"
        android:requestLegacyExternalStorage="true">
</application>

<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">cmpassport.com</domain>
    </domain-config>
</network-security-config>