03 国密一键登录

面向互联网应用的手机号一键登录服务


Andriod SDK集成文档

[TOC]

概述

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

前置条件

  • 国密一键登录SDK支持Android 4.1、minSdkVersion 16及以上版本
  • 国密一键登录SDK支持运营商网关认证、短信验证码认证、国密双向认证
  • 运营商网关认证需要用户开启4G/5G移动网络，短信验证码认证、国密双向认证支持4G/5G/WiFi场景

集成国密一键登录SDK

本地集成

  • 将SDK中libs目录下的aar包拷贝到您工程的libs目录下，如没有该目录需新建。
  • 在build文件的dependencies中添加aar包依赖
repositories {
    flatDir {
        dirs '../app/libs'
    }
}
implementation (name:'loginlibrary',ext:'aar')

<br/>

权限配置

您需要在 AndroidMainfest.xml 文件添加：
    <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" />
权限名称 权限说明 使用说明
INTERNET 允许应用程序联网 用于访问网关和认证服务器
ACCESS_WIFI_STATE 允许访问WiFi网络状态信息 允许程序访问WiFi网络状态信息
ACCESS_NETWORK_STATE 允许访问网络状态 区分移动网络或WiFi网络
CHANGE_NETWORK_STATE 允许改变网络连接状态 设备在WiFi跟数据双开时，强行切换使用数据网络

<br/>

注册应用信息

将AppId配置在项目build.gradle中:

buildTypes {
     release {
       buildConfigField('String', 'APP_ID', '"1111"')
    }
     debug {
       buildConfigField('String', 'APP_ID', '"1111"')
     }
  }

混淆配置

-dontwarn com.unicom.online.account.shield.**
-keep class com.unicom.online.account.shield.** {*;}
-keep class com.safevast.uid.** {*;}

<br/>

SDK的使用

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

日志开关-提示：在初始化之前调用

方法原型： LoginManager.getInstance().showLog(showLog）；

参数 类型 说明
showLog boolean 是否打印日志

<br/>

初始化--提示：SDK的所有其他方法必须在初始化后再调用

初始化的过程中会向服务端请求获取配置参数、动态密码算法，并同步初始化运营商SDK。 <br/> 方法原型： LoginManager.getInstance().init(context, appId, initListener）；

参数 类型 说明
context Context 传ApplicationContext对象
appId String 应用appId
initListener InitListener 初始化回调监听

示例代码：

LoginManager.getInstance().init(getApplicationContext(),BuildConfig.APP_ID,new InitListener() {
            @Override
            public void initLoginResult(int code, String result) {
                if(code == 1000){
                }
            }
        });

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

字段 类型 含义
code int code为1000:成功；其他：失败
result String 初始化结果描述

<br/>

预取号

提前获取手机掩码，以便获得更好的用户体验，建议尽可能前置。（预取号失败可以参考对接流程走SDK提供的短信验证码认证方式） <br/> 示例代码：

LoginManager.getInstance().advanceLogin(new AdvanceLoginListener() {
    @Override
    public void advanceLoginResult(int code, String result) {
        if(code == 1000){
            //预认证成功
            try {
                //设备信息
                JSONObject json = new JSONObject(result);
                //手机掩码
                String mask = json.optString("mask");
                //服务商（移动、联通、电信、密认）
                String service = json.optString("service");
                //服务协议名称
                String termName = json.optString("termName");
                //服务协议URL
                String termUrl = json.optString("termUrl");
            } catch (JSONException e) {
                e.printStackTrace();
            }
        }else if(code == 1001){
            //预认证失败，未获取到设备信息
        }else{
            //预认证失败
        }
    }
});

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

字段 类型 含义
code int code为1000:成功；其他：失败
result String 预认证结果描述，成功会返回JSON数据，按示例解析即可

说明：预取号获得的数据需要在登录/绑定页面显示，预取号会返回移动、联通、电信、密认四个服务商，无需判断类型，根据返回显示即可。 1、用户首次登录满足运营商取号条件，走运营商流量网关认证，服务商字段会返回移动、联通或电信； 2、用户首次登录不满足运营商取号条件，走SDK提供的短信验证码认证，应用自行显示短信验证码页面，无需显示服务商； 3、不管是运营商还是短信验证码，首次认证后都会激活密码模块，密码机会为当前设备生成融合手机号的唯一认证算法（可以理解为下发一个纯软UKey），后续认证都会通过密码算法进行双向认证，服务商字段会返回密认； <br/>

取号

获取本次认证会话密钥加密的手机号码mToken。 <br/> 示例代码：

LoginManager.getInstance().getDeviceInfo(new GetDeviceListener() {
    @Override
    public void getDeviceResult(int code, String result) {
        if(code == 1000){
            try {
                JSONObject json = new JSONObject(result);
                // 密码模块生成的唯一用户标识
                String zuid = json.optString("zuid");
                // 本次认证会话密钥sm4加密的手机号
                String mToken = json.optString("token");
                // 本次认证的签名摘要
                String signature = json.optString("signature");
                loginPost(token,zuid,signature);
            } catch (JSONException e) {
                e.printStackTrace();
            }
        }
    }
});

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

字段 类型 含义
code int code为1000:成功；其他：失败
result String 预认证结果描述，成功会返回JSON数据，按示例解析即可

<br/>

发送短信验证码（收费同一键登录）

短信验证码认证：预认证失败时，可以走SDK提供的短信验证码认证方式，间隔发送时间60s。 说明：密码模块已激活的情况下无法调用此方法；短信验证码默认签名为创建应用时的签名。 <br/> 方法原型：

LoginManager.getInstance().sendLoginSms(num, loginSmsListener);
参数 类型 说明
num String 用户输入的手机号
loginSmsListener LoginSmsListener 发送结果回调

示例代码：

LoginManager.getInstance().sendLoginSms(num, new LoginSmsListener() {
    @Override
    public void loginSmsResult(int code, String result) {

    }
});

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

字段 类型 含义
code int code为1000:成功；其他：失败
result String 发送验证码结果描述

<br/>

校验短信验证码

短信验证码认证：预认证失败时，可以走SDK提供的短信验证码认证方式。（说明：配合发送验证码方法使用） <br/> 方法原型：

LoginManager.getInstance().checkLoginSms(num, sms, checkLoginSmsListener);
参数 类型 说明
num String 用户输入的手机号
sms String 用户输入的验证码
checkLoginSmsListener CheckLoginSmsListener 校验结果回调

示例代码：

LoginManager.getInstance().checkLoginSms(num, sms, new CheckLoginSmsListener() {
    @Override
    public void checkLoginSmsResult(int code, String result) {
        if(code == 1000){
            try {
                JSONObject json = new JSONObject(result);
                // 密码模块生成的唯一用户标识
                String zuid = json.optString("zuid");
                // 本次认证会话密钥sm4加密的手机号
                String mToken = json.optString("token");
                // 本次认证的签名摘要
                String signature = json.optString("signature");
            } catch (JSONException e) {
                e.printStackTrace();
            }
        }
    }
});

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

字段 类型 含义
code int code为1000:成功；其他：失败
result String 校验证码结果描述,成功会返回JSON数据，按照示例解析即可

<br/>

返回码

参数 描述
1000 所有请求返回1000即代表成功
1001 预认证失败，未获取到设备信息
1003 系统版本低于5.0

其他返回码，请结合Result描述具体分析 <br/>

运营商返回码 返回码描述
100 一键登录成功，解析result，可得到网络请求参数
1101 公网 ip 无效(客户 wifi 访问、wap 方式访问等引起获取到的公网 ip 查询不到省份信息)
1102 私网 ip 无效(无法用私网 ip 找到对应的省份信息)
1105 参数信息错误(参数名称、内容错误或者参数丢失再或者加密错误)
1106 应用密钥信息不匹配(密钥信息与包名不一致，android 还需要校验 MD5 信息，也有可能是参数命名错误)
1107 余额不足(使用条数不足)
1201 取号失败
1202 认证失败
1203 获取置换码失败
2101 鉴权失败(参数 sign 名称错误或者 sign 值有误)
2102 accessCode 已失效(accessCode 错误或者过期)
2103 序列号不存在(序列号与授权码和密钥绑定，序列号不存在时返回，即授权码错误或者密钥信息与前台使用 不是一套，或者 seq 已过期)
2201 app_id 无效(appid 未激活或者 appid 错误)
2202 应用信息错误(获取应用信息错误(demo 中 data 参数中 app 信息错误))
2203 sdk 信息错误(获取 sdk 信息错误(demo 中 data 参数中 sdk 信息错误))
2205 接入信息解析错误(用户接入信息解析失败)
2206 流控值超限(用户访问流控超过限制)
3201 系统繁忙(服务端系统出现错误)
3202 内部网关错误
3203 内部路由错误
3204 无支付权限
3206 取号功能暂时不可用
3207 不支持此功能
10100 无网络连接
10101 无数据网络连接
10102 ApiKey 或 PublicKey 不能为空
10103 超时
10104 用户取消登录
10105 切换登录方式
20100 测试次数超限
20101 10 分钟之内最多只能获取 30 个授权码
30200 服务端数据格式出错
-100 数据解密异常(SDK 解密数据失败)

其他返回码请结合result结果描述具体分析

<br/>

工具类

sm4加密方法

示例代码：

String sm4Vaule = AuthManager.getInstance().sm4EncryptMsg(vaule,sessionKey);
参数 类型 说明
vaule String 需要加密的数据
sessionKey byte[] 加密密钥

sm4EncryptMsg((vaule,sessionKey)返回结果，含义如下：

字段 类型 含义
sm4Vaule String sm4加密后结果(16进制字符)

<br/>

页面列表

ITEM_HTML