一.准备工作

概述

本文是闪验SDK_Android端接入文档，用于指导SDK的集成使用。在对接之前您需要花5-10分钟阅读以下条目，可减少对接过程中的问题。

• 常见问题请移步至「对接问题」
• 升级版本请移步至「升级指南」

合规性说明

详见SDK初始化合规性指南

能力介绍

• 一键登录：SDK获取当前流量卡对应的token，通过服务端可置换当前流量卡的手机号码。
• 本机校验：SDK获取当前流量卡对应的token，提供手机号码，通过服务端可校验提供的手机号是否为当前流量卡的手机号码。

** 注意：本机校验和一键登录是两个单独的能力，两者的token不能互用，否则会报"应用能力不匹配"。 **

前置条件

• 闪验SDK支持minSdkVersion 16及以上版本
• 闪验SDK支持中国移动3/4G/5G、联通3/4G/5G、电信4G/5G的取号能力，在3G网络下时延会更高
• 闪验SDK支持单数据网络、数据网络与WiFi网络双开，不支持单WiFi网络
• 对于双卡手机，闪验SDK只对当前流量卡取号，双卡均未开数据流量SDK将会返回错误码

注意：三网运营商内部执行逻辑不同，必须分别使用三网运营商的卡进行测试，防止功能异常

创建应用

注意：应用AppId与包名、包签名一一绑定，如果应用有多个包名或签名不同的马甲包，须创建多个对应包名和签名的应用，否则初始化会报包名或签名校验不通过。

快速体验demo

• Android压缩包中的apk文件夹中是闪验demo的安装包，可以直接安装到Android手机上。
• 在https://github.com/253CL/shanyan_demo_android下载demo示例源码，可直接运行起来测试。

开发环境搭建

本地集成

a.将SDK中libs目录下的aar包拷贝到您工程的libs目录下，如没有该目录需新建。
b.在build文件的dependencies中添加aar包依赖：

repositories {
    flatDir {
        dirs '../app/libs'
    }
}
dependencies {implementation fileTree(include: ['*.aar'], dir: 'libs')}

权限配置

必要权限：

<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"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>

配置权限说明

注册授权页activity

在application标签内配置授权登录activity，screenOrientation和theme可以根据项目需求自行修改

<!-- *******************************授权页*********************************** -->
<activity
   android:name="com.chuanglan.shanyan_sdk.view.ShanYanOneKeyActivity"
   android:configChanges="keyboardHidden|orientation|screenSize"
   android:launchMode="singleTop"
   android:screenOrientation="behind"
    />
<!-- *******************************协议页*********************************** -->
<activity
   android:name="com.chuanglan.shanyan_sdk.view.CTCCPrivacyProtocolActivity"
   android:configChanges="keyboardHidden|orientation|screenSize"
   android:launchMode="singleTop"
   android:screenOrientation="behind"
    /> 

配置对http协议的支持

两种方式（任选其一）：
方式一：在application标签中配置usesCleartextTraffic，示例如下

<application
    android:name=".view.MyApplication"
    ***
    android:usesCleartextTraffic="true"
    ></application>

方式二：将域名10010.com设置为白名单，示例如下

<application
    android:name=".view.MyApplication"
    ***
    android:networkSecurityConfig="@xml/network_security_config"
    ></application>

network_security_config.xml文件：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">10010.com</domain>
    </domain-config>
</network-security-config>

混淆规则

-dontwarn com.cmic.gen.sdk.login.**
-keep class com.cmic.gen.sdk.login.**{*;}
-dontwarn cn.com.chinatelecom.account.**
-keep class cn.com.chinatelecom.account.**{*;}
-keep class com.unicom.online.account.shield.** {*;}
-keep class com.unicom.online.account.kernel.** {*;}
-dontwarn org.bouncycastle.**
-keep class org.bouncycastle.** { *;}

资源压缩过滤

如果使用AndResGuard资源压缩，需添加过滤，参考demo示例：

"R.anim.umcsdk*",
"R.drawable.umcsdk*",
"R.layout.layout_shanyan*",
"R.id.shanyan_view*",

如果使用系统shrinkResources true，需要在raw/keep里面配置资源过滤keep.xml：

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools" tools:keep="R.anim.umcsdk*,
    R.drawable.umcsdk*,
    R.layout.layout_shanyan*,
    R.id.shanyan_view*" />

添加示例：

通过上面的几个步骤，工程就配置完成了，接下来就可以在工程中使用闪验SDK进行开发了。

二.一键登录api

0.提升授权页的打开速度

• 建议在执行拉取授权登录页的方法前，提前一段时间调用预取号方法，中间最好有2-3秒的缓冲（因为预取号方

  法需要1~3s的时间取得临时凭证）
  

• 如果条件允许，超时时间设置为6秒有助于网络不好的时候取号成功率，SDK默认4秒。

1.初始化

调用SDK其他流程方法前，请确保已调用过初始化，否则会返回未初始化。（会采集信息，建议放到同意协议后调用）

方法原型

public void init(Context context, String appId, InitListener initListener)

参数描述

示例代码

   OneKeyLoginManager.getInstance().init(getApplicationContext(), appId, new InitListener() {
                            @Override
                            public void getInitStatus(int code, String result) { 
                            }
                        });

getInitStatus(int code, String result)返回参数code和result，含义如下：

2.预取号

• 【可选方法】获取取号临时凭证；建议在调用拉起授权页前2~3秒调用，可以缩短拉起授权页耗时；如果启动app就需要展示授权页，中间没有2~3秒的间隔，不建议调用，起不到缩短时间的效果。
• 请勿与拉起授权登录页同时或之后调用。
• 避免大量资源下载时调用，例如游戏中加载资源或者更新补丁的时

示例代码：

OneKeyLoginManager.getInstance().getPhoneInfo(new GetPhoneInfoListener() {
    @Override
    public void getPhoneInfoStatus(int code, String result) {
    }
});

getPhoneInfoStatus(int code, String result)返回参数code和result，含义如下：

3.拉起授权页&获取token

• 拉起授权页方法将会调起运营商授权页面。已登录状态请勿调用 。
• 每次调用拉起授权页方法前均需先调用授权页配置方法，否则授权页可能会展示异常。
• 必须保证上一次拉起的授权页已经销毁再调用，否则SDK会返回请求频繁。
• 拉起一次授权页，登录按钮最多只能点击4次，第五次默认会置灰，不返回信息。

方法原型：

public void openLoginAuth(boolean isFinish, OpenLoginAuthListener openLoginAuthListener, OneKeyLoginListener oneKeyLoginListener){}

参数描述

示例代码

OneKeyLoginManager.getInstance().openLoginAuth(false, new OpenLoginAuthListener() {
    @Override
    public void getOpenLoginAuthStatus(int code, String result) {
    }
}, new OneKeyLoginListener() {
    @Override
    public void getOneKeyLoginStatus(int code, String result) {
    }
});

getOpenLoginAuthStatus(int code,String result)返回参数code和result，含义如下：

getOneKeyLoginStatus(int code,String result)返回参数code和result，含义如下：

当外层code为1000时，result的返回为

{"token":"A1-Gv-q1ORHeOOZyFe261VJAD_JetfjvVNzJyoQqJxq_lSY39xXmtagZ0VA66IMr7htOQWSHBhnvM4wNDJlZV0DsUtGZDU640ItGCdYuA0N0k3cjkcg4omJWm_1YEMEa55TE-cCo6DsE3LAsc7nmzp5ortoS9f5QjBV9RGGBQYDbX74Er2N9Or8alWzAyP5KzvhJ3mUe3gQFWjYomTpw-fohsjv8ldi0AqaBUxYittipt3l69j3uMK07WAWe_kmSj1biQvbs5hVnCKofFXyvhw_9A"}

含义如下：

4.置换手机号

当一键登录外层code为1000时，会获取到置换手机号所需的token。请参考「服务端」文档来实现获取手机号码的步骤

5.其他API

a.设置log开关

OneKeyLoginManager.getInstance().setDebug(true);

注：需要放到SDK初始化之前调用，用ProcessShanYanLogger可以过滤方法调用及回调等信息，用UIShanYanTask可以过滤UI配置相关日志，用ActivityLifecycleShanYanTask可以过滤界面生命周期相关日志。

b.设置loading显示状态

点登录按钮时默认会显示loading，本方法可在loading显示后改变loading状态时调用，如果需要点击登录按钮不显示loading，请请看常见问题

 OneKeyLoginManager.getInstance().setLoadingVisibility(false);

参数描述

c.设置协议勾选框状态

本方法仅在授权页拉起后想改变CheckBox状态时使用，设置进入授权页时的默认状态，请使用授权页配置ShanYanUIConfig里面的setPrivacyState方法

 OneKeyLoginManager.getInstance().setCheckBoxValue(false);

参数描述

d.清理预取号缓存

OneKeyLoginManager.getInstance().clearScripCache(getApplicationContext());

e.获取运营商类型

OneKeyLoginManager.getInstance().getOperatorType(getApplicationContext());

返回值4种：CMCC、CUCC、CTCC、UNKNOWN_OPERATOR；
释义：CMCC（移动）；CUCC（联通）；CTCC（电信）； Unknown_Operator（无SIM卡或非三网运营商）

f.设置预取号超时时间

需要初始化之前调用，方法原型：

OneKeyLoginManager.getInstance().setTimeOutForPreLogin(6);

参数描述

注：不建议设置小于4的值，否则可能会导致超时的概率增加。

g.获取运营商信息

OneKeyLoginManager.getInstance().getOperatorInfo(getApplicationContext());

返回示例：

{"telecom":"CTCC",
 "protocolName":"天翼服务及隐私协议",
 "protocolUrl":"https:\/\/e.189.cn\/sdk\/agreement\/detail.do?hidetop=true"}

返回信息描述

h.授权页协议点击事件监听

      OneKeyLoginManager.getInstance().setPrivacyOnClickListener((url, name) -> {
        });

返回参数：

i.设置是否只允许主进程调用

OneKeyLoginManager.getInstance().checkProcessesEnable(false);

参数描述

j.授权页点击事件监听

需要对授权页点击事件监听的用户，可调用此方法监听授权页点击事件，无此需求可以不写。

   OneKeyLoginManager.getInstance().setActionListener(new ActionListener() {
            @Override
            public void ActionListner(int type, int code, String message) {
            }
        });

ActionListners(**int **type,int code,String message)返回参数含义如下：

k.销毁授权页

A.自动销毁
1.在授权登录页面，当用户主动点击左左上角返回按钮时，返回码为1011，授权页面将自动销毁授权页；
2.当用户点击物理返回键返回键（相当于取消登录），返回码为1011，授权页面将自动销毁授权页
3.当用户设置一键登录或者其他自定义控件为自动销毁时，得到回调后，授权页面将自动销毁
B.手动销毁

OneKeyLoginManager.getInstance().finishAuthActivity();

注意：销毁授权页时，请不要在销毁后回到的界面主线程中做耗时操作，避免堵塞授权页onDestroy方法，导致再次调用拉起授权页时报请求频繁。

l.跳转到SDK内部协议页

 public void startPrivacyProtocolActivity(Context context, String url, String name){}

参数描述

m.授权页启动|销毁监听

        OneKeyLoginManager.getInstance().setLoginActivityStatusListener(new LoginActivityStatusListener() {
            @Override
            public void onActivityCreated(Activity activity) {
            }
            @Override
            public void onActivityDestroyed(Activity activity) {
            }
        });

n.获取授权页协议勾选框CheckBox对象

需要在授权页activity创建后并且未销毁的情况下调用。

CheckBox privacyCheckBox=OneKeyLoginManager.getInstance().getPrivacyCheckBox();  

6.授权页界面配置

可选方法，SDK有内置默认授权页配置，如需自定义界面，请调用此方法。

a.设计规范

闪验登录授权界面设计规范
注意：开发者不得通过任何技术手段，将授权页面的登录按钮、隐私栏、号码栏内容隐藏、覆盖，对于接入闪验SDK并上线的应用，我方和运营商会对授权页面做审查，如果有出现未按要求设计授权页面，我方有权将应用的一键登录功能下线。

b.授权页配置

调用该方法可实现对三网运营商授权页面个性化设计，配置一次有效，每次调用拉起授权页方法前必须先调用该方法，否则授权界面会展示异常，具体实现可参考demo示例的ConfigUtils配置类。（三网界面配置内部实现逻辑不同，请务必使用移动、联通、电信卡分别测试）

方法原型

public void setAuthThemeConfig(ShanYanUIConfig shanPortraitYanUIConfig, ShanYanUIConfig shanLandYanUIConfig) {}

参数说明

示例代码

OneKeyLoginManager.getInstance().setAuthThemeConfig(ConfigUtils.getCJSConfig(getApplicationContext()), ConfigUtils.getCJSLandscapeUiConfig(getApplicationContext()))

#### 背景 三选一，支持图片，gif图，视频

整体属性

状态栏

导航栏（默认高度：50dp）

logo图标

号码栏

登录按钮（默认高度：46dp）

隐私栏

如果需要增加3个以上自定义协议，可使用如下方法（具体可参数demo示例源码A配置）：

运营商slogan（**提供认证服务）

上海璟梦信息科技有限公司slogan（上海璟梦信息科技有限公司253提供技术支持；默认：隐藏）

登录loading

添加自定义控件

1.添加相对控件（指定在登录按钮和协议栏之间；默认铺满按钮和协议之间区域）
注意：使用此方法添加自定义控件时，登录按钮必须使用setLogBtnOffsetY设置偏移，协议栏必须使用setPrivacyOffsetBottomY设置偏移，否则可能不显示

2.添加普通自定义控件
方法原型

public ShanYanUIConfig.Builder addCustomView(View view, boolean isFinish, boolean type, ShanYanCustomInterface shanYanCustomInterface) {}

参数说明

注意：如果添加布局为自定义控件，监听实现请参考demo示例。

设置弹窗样式

调用该方法可实现将授权页设置成弹窗样式。

方法原型

public ShanYanUIConfig.Builder setDialogTheme(boolean isdialogTheme, int dialogWidth, int dialogHeight, int dialogX, int dialogY ,boolean isDialogBottom) {}

参数说明

注意：设置弹窗效果背景的透明度需要在Manifest.xml里面配置授权界面主题样式
样式示例：
1.为授权界面的activity设置弹窗theme主题，电信授权页为例：

<activity
   android:name="com.chuanglan.shanyan_sdk.view.ShanYanOneKeyActivity"
   android:configChanges="keyboardHidden|orientation|screenSize"
   android:launchMode="singleTop"
   android:screenOrientation="behind"
    android:theme="@style/Theme.ActivityDialogStyle" />

2.设置theme主题的style样式

<style name="Theme.ActivityDialogStyle" parent="Theme.AppCompat.Light.NoActionBar">
    <!--背景透明-->
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:windowIsTranslucent">true</item>
    <!--dialog的整个屏幕的背景是否有遮障层-->
    <item name="android:backgroundDimEnabled">true</item>
</style>

注意：如果需要触摸弹窗外部销毁授权页，style的parent请使用系统dialog相关主题。

弹窗样式时的遮盖层灰度设置

设置横竖屏

在manifest文件中，指定授权页activity的screenOrientation即可

注意：只有全屏不透明的activity才能指定方向，否则在8.0系统版本上会报“Only fullscreen opaque activities can request orientation”或其他异常。
即：弹框或者透明主题，授权页不能指定方向。如需指定方向，可以指定授权页前个页面的方向，授权页设置跟随前个界面方向，即：“android:screenOrientation=“behind””

隐私协议提示弹框（具体实现见常见问题）

c.协议页配置

三.本机校验api

注：本机认证同免密登录，需要初始化，本机认证、一键登录可共用初始化，两个功能同时使用时，只需调用一次初始化。

1.初始化

同一键登录初始化

2.本机校验获取token

在初始化执行之后调用，本机号校验界面需自行实现，可以在多个需要校验的页面中调用。
示例代码：

 OneKeyLoginManager.getInstance().startAuthentication(new AuthenticationExecuteListener() {
                        @Override
                        public void authenticationRespond(int code, String result) {
                        }
                    });

authenticationRespond(int code,String result)返回参数code和result，含义如下：

当外层code为2000时，result的返回为

{"token":""}

含义如下：

3.校验手机号

当一键登录外层code为2000时，会获取到检验手机号所需的token。请参考「服务端」文档来实现检验手机号码的步骤。

四.返回码

此表为SDK外层返回码，如需查看内层码及服务端返回码，请查看官网返回码