Android客户端接入

1. 概述

官网下载SDK后进行解压，解压后包含三个文件是：

• SDK说明文档。
• Demo工程：PhoneNumberAuthDemo。
• aar包。

SDK同时包含了本机号码校验和一键登录两个功能。

号码认证服务包含本机号码校验和一键登录时两个不同的功能，使用场景不一样，无需一起使用。

本机号码校验使用场景：⽤户输⼊⼿机号码，通过SDK获取token，服务端携带输⼊的⼿机号码和 token去运营商⽹关进⾏校验，返回的结果时⽤户当前上⽹使⽤的号码与输⼊的号码是否⼀致。

一键登录使用场景：⽤户⽆需输⼊⼿机号码，SDK会拉起授权⻚，⽤户确认授权后，SDK会获取 token，服务端携带token到运营商⽹关获取⽤户当前上⽹使⽤的号码，并返回给App服务端。

2. 准备工作

• 请确保您的终端设备已经开启了4G⽹络（联通、移动⽀持3G⽹络，但接⼝耗时会增加）。
• 请确保已经在阿⾥云控制台开通了号码认证服务并创建了对应的⽅案，点击进⼊阿⾥云控制台。
• 您也可以登录阿⾥云官⽹查看接⼊流程，点击查看完整使⽤流程。

3. 运行demo工程

4. 开发环境搭建

1. 拷⻉aar包。

   下载SDK并解压后，将aar拷⻉⾄⼯程的libs⽬录下。

2. App⼯程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:theme="@style/authsdk_activity_dialog"          使用弹窗模式必须添加！！！
       android:launchMode="singleTop" />  
   <!--协议页面webview-->  
   <activity  
       android:name="com.mobile.auth.gatewayauth.activity.AuthWebVeiwActivity"  
       android:configChanges="orientation|keyboardHidden|screenSize"  
       android:exported="false"  
       android:launchMode="singleTop" 
       android:screenOrientation="behind" />  
    <!--移动授权页--> 
    <activity  
       android:name="com.cmic.sso.sdk.activity.LoginAuthActivity"  
       android:configChanges="orientation|keyboardHidden|screenSize"
       android:exported="false"  
       android:launchMode="singleTop" />
               

3. 混淆keep规则，已经将混淆规则写入aar包，不再需要单独配置。
4. 若开启资源混淆，需要配置。

   "R.drawable.authsdk*",
   "R.layout.authsdk*",
   "R.anim.authsdk*",
   "R.id.authsdk*",
   "R.string.authsdk*",
   "R.style.authsdk*",

5. lib依赖：点击下载依赖包。
6. 使用v4包com.android.support:support-v4版本高于25.4.0或者v7包com.android.support:appcompat-v7版本高于25.4.0。
7. 权限列表。

   <uses-permission android:name="android.permission.INTERNET" />   <!-- 网络访问 -->
   <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" /> <!-- 开关wifi状态，解决国内机型移动网络权限问题需要 -->

8. Android 9.0以上支持HTTP配置。
   • App AndroidManifest.xml里面，Application节点增加usesCleartextTraffic配置。

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

   • 目前中国移动提供的个别接口为HTTP请求，对于全局禁用HTTP的项目，需要设置HTTP白名单。以下为运营商HTTP接口域名：onekey.cmpassport.com，enrichgw.10010.com。具体可以参见Demo代码。
9. Androidx适配问题。

   由于SDK使用的是support包，所以使用AndroidX需要在gradle.properties配置。

   android.useAndroidX=true
   android.enableJetifier=true

5. SDK方法说明

5.1 获取认证实例（getInstance）

/**
 * 获取号码认证服务示例，此实例为单例，获取多次为同一对象
 * @param context       Android上下文
 * @param tokenListener 需要实现的获取token回调
 * @return PhoneNumberAuthHelper
 */  
public static PhoneNumberAuthHelper getInstance(Context context,  TokenResultListener tokenListener)

5.2 检查认证环境（checkAuthEnvEnable）

/**
 * SDK环境检查函数，检查终端是否⽀持号码认证，通过TokenResultListener返回code
 * type 1：本机号码校验 2: ⼀键登录
 * 600024 终端⽀持认证
 * 600013 系统维护，功能不可⽤
 */
 public void checkEnvAvailable(@IntRange(from = 1, to = 2) int type)

5.3 加速本机号码校验（accelerateVerify）

/**  
 public void accelerateVerify(int overdueTime, final PreLoginResultListener listener);

5.4 本机号码校验token(getVerifyToken)

/**
* 获取认证token
*
* @param totalTimeout 超时时间 单位ms
*/
 public void getVerifyToken(final int totalTimeout)

5.5 加速授权页拉起（accelerateLoginPage）

/**
* 加速授权⻚唤起
*
* @param overdueTime 预取号有效期
* @param listener    预取号回调
*/
public void accelerateLoginPage(final int overdueTime, final PreLogin ResultListener listener)

5.6 ⼀键登录唤起授权页（getLoginToken）

/**
* 获取登录token 调起⼀键登录授权⻚⾯，在⽤户授权后获取⼀键登录的Token
*
* @param totalTimeout 超时时间 单位ms
*/
public void getLoginToken(final Context context, final int totalTimeout)

5.7 退出授权页（quitLoginPage）

/**
* 退出授权认证⻚
* sdk完成回调之后不会关闭授权⻚，需要开发者主动调⽤quitLoginPage退出授权⻚
*/
public void quitLoginPage()

5.8 关闭授权页loading（hideLoginLoading）

/**
* 关闭授权⻚loading
* sdk完成回调之后不会关闭loading，需要开发者主动调⽤hideLoginLoading关闭loading
*/
public void hideLoginLoading()

5.9 返回默认上⽹卡运营商（getCurrentCarrierName）

/**
* 返回默认上⽹卡运营商
*
* @return CMCC、CUCC、CTCC
*/
public String getCurrentCarrierName()

5.10 使用xml添加自定义控件至⼀键登录授权页 （addAuthRegisterXmlConfig）

/**
* 添加⾃定义View
*
* @param xmlConfig
*/
public void addAuthRegisterXmlConfig(AuthRegisterXmlConfig xmlConfig)

⼀次add，XML内绘制的⾃定义控件全部添加完成。

初始化 addAuthRegisterXmlConfig 类时需要先调静态内部类Builder()⾥⾯的 2 个⽅法。

• setLayout： 开发者传⼊⾃定义的控件的xml资源ID。
• AbstractPnsViewDelegate：授权⻚使⽤xml添加⾃定义布局时，可以配合该Delegate类实现xml中相关view的操作，⽐如事件监听以及动态UI改动等等，当xml对应的view加载后SDK将调⽤ onViewCreated(View)⽅法通知view已经创建OK，此时可以获取xml中的view并进⾏相关事件绑定等操作。

调用示例：

mAlicomAuthHelper.addAuthRegisterXmlConfig(new AuthRegisterXmlConfig .Builder()
 .setLayout(R.layout.xxxxxx, new AbstractPnsViewDelegate() {
    @Override public void onViewCreated(View view) {
        //这⾥返回的View，不建议⽤强引⽤，如果要⽤，请及时释放，否则容易造成内存泄 漏
        findViewById(R.id.xxxx).setOnClickListener(new View.OnClickL istener() {
            @Override public void onClick(View v) {
                //do something
            }
        });
    }
})
.build());

5.11 添加代码编写的自定义控件至登录授权页（addAuthRegistViewConfig）

/**
* 动态添加控件
*
* @param viewID 开发者⾃定义控件名称
* @param viewConfig 配置开发者⾃定义控件的控件来源、位置和处理逻辑
*/
public void addAuthRegistViewConfig(String viewID, AuthRegisterViewConfig viewConfig)

初始化 AuthRegisterViewConfig 类时需要先调静态内部类Builder()⾥⾯的 3 个⽅法。

• setView： 开发者传⼊⾃定义的控件，开发者需要提前设置好控件的布局属性，SDK 只⽀持 RelativeLayout 布局。

• setRootViewId：设置控件的位置，⽬前SDK 授权⻚允许在3个位置插⼊开发者控件。

  RootViewId.ROOT_VIEW_ID_TITLE_BAR，标题栏。

  RootViewId.ROOT_VIEW_ID_BODY，授权⻚空⽩处。

  RootViewId.ROOT_VIEW_ID_NUMBER，授权⻚号码掩码区域。

• setCustomInterface：设置控件事件。

  public Builder setCustomInterface(CustomInterface customInterface)。

调⽤示例：

mAlicomAuthHelper.addAuthRegistViewConfig("switch_acc_tv", new AuthRe gisterViewConfig.Builder()
.setView(mRL)
.setRootViewId(AuthRegisterViewConfig.RootViewId.ROOT_VIEW_ID_BODY)
.setCustomInterface(new CustomInterface() {
   @Override
    public void onClick(Context context) {
    startActivityForResult(new Intent(context, SecondActivity.class), 1234);
    }
 }).build());

获取 token 成功之后，需把通过setView()注⼊进去的view 置为 null。

5.12 ⼀键登录修改授权页主题（setAuthUIConfig）

 /**
* 修改授权⻚⾯主题，开发者可以通过 此⽅法修改授权⻚⾯主题，需在 getLoginToken接⼝ 之前调⽤
*
* @param authUIConfig 登录授权⻚UI⾃定义配配置
*/
public void setAuthUIConfig(AuthUIConfig authUIConfig)

调⽤示例：

setAuthUIConfig(new AuthUIConfig.Builder()
.setLogBtnText("⼀键登录")
.setLogBtnClickableColor(Color.BLACK)
.setLogBtnUnClickableColor(Color.BLUE)
.setLogBtnTextColor(Color.WHITE).setLogoHidden(false)
.setNavColor(0xff026ED2)
.setNavText("免密登录")
.setNavTextColor(Color.WHITE)
.setNumberColor(Color.WHITE)
.setNumberSize(28)
.setNumberColor(0xff000000).create());

6. SDK回调说明

6.1 获取token回调

• 回调返回的ret都通过 TokenRet tokenRet = JSON.parseObject(ret, TokenRet.class) 解析。
• 授权⻚唤起成功、获取token成功都会回调onTokenSuccess⽅法（要区分两次成功可以通过返回码来区分）。
• 获取token失败会回调onTokenFailed。
• 获取token回调示例代码：

  mTokenListener = new TokenResultListener() {
   @Override
   public void onTokenSuccess(final String ret) {
   MainActivity.this.runOnUiThread(new Runnable() {
                  @Override
                  public void run() {
                      /*
                       *   setText just show the result for get token。
                       *   use ret to verfiy number。
                       */
                      //ResultCode#CODE_START_AUTHPAGE_SUCCESS是授权⻚唤 起成功码，若不需要处理，则过滤
                       if (ResultCode.CODE_START_AUTHPAGE_SUCCESS.equa ls(tokenRet.getCode())) {
                             return;
                      }
  
                      TokenRet tokenRet = JSON.parseObject(ret, TokenR et.class);
                      if (tokenRet != null) {
                          token = tokenRet.getToken();
                      }
                      mAlicomAuthHelper.quitLoginPage();
                  }
              });
          }
  
          @Override
          public void onTokenFailed(final String ret) {
              MainActivity.this.runOnUiThread(new Runnable() {
                  @Override
                  public void run() {
                      /*
                       *  setText just show the result for get token
                       *  do something when getToken failed, such as u se sms verify code.
                       */
                      TokenRet tokenRet = JSON.parseObject(ret, TokenR et.class);
                      mAlicomAuthHelper.quitLoginPage();
                  }
              });
          }
      };

6.2 加速唤起授权页/加速本机号码校验回调

public interface PreLoginResultListener {
/**
* @param  vendor 返回预取成功运营商
*/
void onTokenSuccess(String vendor);
/**
* @param vendor 返回预取失败运营商
* @param ret 返回失败原因
*/
void onTokenFailed(String vendor, String ret);
}

预取号回调示例代码：

mPreLoginResultListener = new PreLoginResultListener() {
            @Override
            public void onTokenSuccess(final String s) {
                MainActivity.this.runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                       /*
                        *  推荐在登录⻚初始化的时候调⽤
                        *  如果没有合适的调⽤时机
                        *  不调⽤此接⼝也没关系
                        *  千万不要App冷启动初始化就调⽤！！！！
                        *  不要调⽤完预取号后⻢上调⽤getLoginToken！！！
                        *  最好判断⽤户是否登录，若已登录不要使⽤此接 ⼝！！！！
                        */
                        mRetTV.setText("预取号成功:" + s);
                    }
                });
            }

            @Override
            public void onTokenFailed(final String s, final String s 1) {
                /*
                 *  预取号调⽤失败
                 *  不⽤太关注，还是可以直接在⽤户点击"登录"时，调⽤getLoginT oken
                 */
                mRetTV.setText("预取号失败:" + s + s1);
            }
        });
     }
}

6.3 控件点击事件回调

授权页控件点击事件通过此回调返回

public interface AuthUIControlClickListener {
/**
*
* @param code     控件点击事件code
* @param context  Android上下⽂
* @param jsonObj  点击事件返回的具体内容，不同控件返回的事件内容有所不同
*/
void onClick(String code, Context context, JSONObject jsonObj);
}
            

控件点击事件回调示例代码

mAlicomAuthHelper.setUIClickListener(new AuthUIControlClickListener( ) {
            @Override
            public void onClick(String code, Context context, JSONObj ect jsonObj) {
                Log.e("xxxxxx", "OnUIControlClick:code=" + code + ", jsonObj=" + (jsonObj ==     null ? "" : jsonObj.toJSONString()));
}
});

6.4 建议代码调用顺序

/*
*   1.初始化获取token实例
*/
mTokenListener = new TokenResultListener() {}

/*
*   2.初始化SDK实例
*/
mAlicomAuthHelper = PhoneNumberAuthHelper.getInstance(context, mToke nListener);
/*
*   3.设置SDK密钥
*/
mAlicomAuthHelper.setAuthSDKInfo();
/*
*   4.检测终端⽹络环境是否⽀持⼀键登录或者号码认证，根据回调结果确定是否可以使⽤⼀ 键登录功能
*/
mAlicomAuthHelper.checkEnvAvailable(PhoneNumberAuthHelper#SERVICE_TY PE_LOGIN);

/*
*   5.若步骤4返回true，则根据业务情况，调⽤预取号或者⼀键登录接⼝
*     详⻅demo接⼊⼯程
*/
mAlicomAuthHelper.getLoginToken(context, 5000);

6.5 ⼀键登录获取⼿机号

当您成功获取到getLoginToken成功获取token后，将token传递至您的服务端，服务端携带token调用阿里云的getMobile接口即可进行最终的取号操作。

6.6 本机号码校验结果

当您成功获取到getVerifyToken成功获取token后，将token传递至您的服务端，服务端携带token调用阿里云的VerifyMobile接口即可进行最终的取号操作。

7. SDK返回码

除阿里云SDK返回码外，运营商返回码见阿里云官网运营商SDK错误码。

7.1 授权页点击事件响应码

7.2 Crash收集（建议开启）

功能介绍

从v2.10.0版本之后，号码认证SDK支持自己收集SDK内部的Crash问题，方便线上问题排查。客户可以自行选择是否让SDK支持该能力，如果需要支持，则要额外接入SDK包中提供的crashshield-release.aar

集成指南

crashshield-release.aar

implementation 'com.ucweb.wpk:crashsdk-java:3.2.0.1'

混淆配置

增加混淆配置

-keep class com.uc.crashsdk.** { *; }
-keep interface com.uc.crashsdk.** { *; }

注意事项

由于uc的crash收集原理与市面常见crash收集库的原理类似，如果App自身原本就有crash收集能力，建议将自身的crash库放在前面加载，uc的crash不会替换原有的crash收集能力，而是会形成链式传递，且只会收集跟号码认证SDK相关的crash，其他的crash信息不会收集。

8. 一键登录授权页面说明

8.1 授权页面设计规范

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

8.3 授权页配置说明

8.3.1 授权页导航栏

8.3.2 授权页Logo

8.3.3 授权页Slogan

8.3.4 授权页号码栏

8.3.5 授权页登录按钮

8.3.6 授权页隐私栏

授权页面的隐私栏请勿用任何手段进行遮掩，否则会导致号码认证失败。

8.3.7 切换方式控件

8.3.8 页面相关函数

9. 常见问题

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

• 首先检测sim卡有没有欠费，能不能通过移动网络上网。
• Android 国内某些厂商的系统，wifi 网络权限与移动网络权限是分开管理的，检测App是否仅仅只有WLAN 网络权限，而移动蜂窝网络权限缺失。

2.checkEnvAvailable函数返回false？

• 检测是否有插入sim卡
• 检测蜂窝网络开关是否开启

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

• 手机设置检测网络制式，中国移动支持2G/3G/4G、中国联通支持3G/4G、中国电信支持4G，但各大运营商网络在4G网络成功率较高
• 接口超时时间是否过短，建议3000~5000ms
• SIM能否欠费，是否可以蜂窝网络上网。
• 切换卡的过程中，需要等网络稳定后，再使用认证登录功能。

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

• 使用默认上网卡进行一键登录认证。

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

• ⼿机⽹络是否连接了代理。
• ⼿机是否处于hook状态，或者安装了相关的hook框架。
• App是否处于attached状态。
• ⼿机是否被root。
• 是否在模拟器环境中运⾏。
• App是否处于调试状态，使⽤ getReporter.setLoggerEnable(true) 可以关闭此项检测。

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:usesCleartextTraffic="true"，配置android:networkSecurityConfig文件
• 如果设置了networkSecurityConfig文件，请在networkSecurityConfig文件里面配置

<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">enrichgw.10010.com</domain> <!-- 联通内部5G请求域名，开发者需要添加 -->
        <domain includeSubdomains="true">onekey.cmpassport.com</domain>  <!-- 移动内部请求域名，开发者需要添加 -->
    </domain-config>
</network-security-config>

12. setSDKAuthSDKInfo的密钥如何获取？

登录阿里云控制台，进入认证方案管理，点击”密钥“进行复制，建议维护在App服务端。此密钥不是阿里云的AccessKey，AccessSecret。

13. 内存泄漏

• Toast内存泄漏
  • 协议没勾选点击⼀键登录按钮显示Toast，退出授权⻚⻚出现内存泄漏。解决办法是 AuthUIConfig.setLogBtnToastHidden(true)隐藏默认Toast，根据点击事件的code⾃⼰显示 Toast即可。
  • ⻚⾯⾮法修改，当授权⻚号码栏、⼀键登录Button、协议栏出现重叠或者遮挡时点击⼀键登录按钮，显示Toast⻚⾯⾮法修改。解决办法，查看图层解决重叠即可。
• TokenResultListener内存泄漏

  SDK内部会持有外部设置进来的TokenResultListener，在⼀键登录功能使⽤完毕之后通过PhoneNumberAuthHelper.setAuthListener(null)将回调置空即可。

14.AAR介绍

所有的AAR都是必须。

• crashshiled-xx-release.aar：SDK的内部的crash防护和收集库，可以减少SDK的崩溃率，在SDK发生问题时不会影响接入者的App。
• logger-xx-release.aar：SDK内部用于收集日志信息和监控告警的。
• main-xx-release.aar：SDK内部的一些核心工具类，比如线程池，json解析等等。