Android_SDK
所有文档

          号码认证服务 PNVS

          Android_SDK

          1.概述

          本项目是一款在Android系统上实现手机号码一键登录的SDK。此SDK具备风险设备检测、运营商一键登录等多种功能。

          2.准备工作

          在使用此SDK之前,需要开发者将宿主APK提供给本项目接口人进行后台配置。配置完成后生成对应appkey、seckey字段,在此SDK初始化时使用。

          3.集成步骤

          此SDK对外提供多个版本供宿主集成,主要区别是集成的运营商可定制化,可以选择集成单个或者多个运营商。

          第一步:下载对应标准版SDK。

          第二步:将aar导入到libs目录下。

          第三步:在build.gradle配置aar依赖。

          dependencies  {
          //name 为 libs 目录下.aar 文件名称,ext 为.aar 的扩展名
          implementation(name: 'embed_ssolibrary-haotian-debug', ext: 'aar')}

          4.API接口

          4.1初始化接口

          宿主程序启动后在应用的Application类的onCreate中调用初始化接口:

          HTSSOManager.init(Context context, String appkey, String seckey);

          宿主程序需要确保在使用一键登录功能的进程中初始化本SDK。

          参数说明

          String appkey、String seckey:用于服务器的访问校验,是本SDK的渠道凭证,集成之前需要向接口人申请。这两个 key 是和集成宿主的包名和签名唯一关联的。如果包名或者签名有变化需要重新申请。

          4.2用户授权隐私协议状态设置接口

          初始化时根据用户对隐私协议授权行为设置对应状态。

          HTSSOManager.setUserAuthPrivacyState(Context context, boolean state);

          参数说明

          1. context:上下文环境。
          2. state:用户同意隐私协议时设置为true,拒绝时设置为false。

          4.3预取号接口

          在需要使用一键登录功能的Activity中调用,调用该接口会加速后面授权界面打开速度,强烈建议提前调用。在调用此接口时,必须确保已调用初始化接口,预取号接口提供2种。

          HTSSOManager.preLogin(Context ctx, long time0ut, new  HTSSOManager.IHTSSOLoginListener () {
                     @Override
                     public void onFinish(String info) {
                     }
                 });

          参数说明

          1. ctx:环境上下文。
          2. timeOut:接口超时时间,建议设置为5秒及以上。
          3. listener:预取号结果回调接口。
          HTSSOManager.preLogin(Context ctx, long time0ut, int operateType,
          new HTSSOManager.IHTSSOLoginListener () {
                      @Override
                      public void onFinish(String info) {
                      }
                  });

          参数说明

          1. ctx:上下文Context。
          2. timeOut:接口超时时间,建议设置为5秒及以上。
          3. operateType:选择登录的运营商类别,如已经知道当前用户手机卡为移动,则传入移动类别。可选值:1.移动 2.联通 3.电信
          4. listener:预取号结果回调接口。

          注意:

          1.首次使用运营商一键登录时,必须开启对应运营商数据流量。

          2.第一个登录接口内部判断sim卡运营商并且调用对应运营商接口,第二个接口为调用指定运营商登录接口,如果集成的为单个或者全部运营商的sdk,指定运营商参数失效。

          1. 预取号数据有效期为1小时

          4.4 打开授权页接口

          HTSSOManager.openLoginPage (Context context,long timeOut,new
            HTSSOManager.IHTSSOLoginListener() {
                      @Override
                      public void onFinish(String info) {}
                  });

          参数说明

          1. ctx:上下文Context,如果要设置界面跳转动画,此处context必须为Activity。
          2. timeOut:接口超时时间,建议设置为5秒及以上。
          3. listener:预取号结果回调接口。

          注意:调用该接口强烈建议先调用了预取号接口,能加快界面打开速度

          4.5 关闭授权页接口

          HTSSOManager.closeoPage()

          授权页面打开后,如果用户授权我们会正常返回信息,集成方决定什么时候关闭页面,如果用户取消,则我们直接关闭授权页面并且返回对应错误码。

          4.6 获取当前SIM卡运营商接口

          new HTSSOManager.getCurrentOperatorName(Context context) 

          参数说明:

          Context context:上下文Context

          返回值说明:

          CMCC:中国移动

          CTCC:中国电信

          CUCC:中国联通

          没有sim卡返回null

          4.7 设置授权界面接口

          昊天sdk内置两种样式的授权页面,集成方可以自行选择:

          全屏模式

          image.png

          弹窗模式

          image.png

          其中很多元素均提供对应接口,可以自定义您的授权页样式 (1)修改授权页样式接口

          HTSSOManager.setAuthThemeConfig(Context context,SSOAuthThemeConfig config) 

          参数说明:

          Context:环境上下文

          SSOAuthThemeConfig:授权页样式

          调用示例:

          HTSSOManager.setAuthThemeConfig(this.getApplicationContext(),
                  new SSOAuthThemeConfig.Builder(this.getApplicationContext(),
                          SSOAuthThemeConfig.TYPE_FULL_SCREEN)
          .setThemeId(R.style.auth)
          .setLogBtnText(“一键登录”)
          .setLogBtnTextColor(Color.BALCK)
          .setLogBtnImagePath(“btn_select”)
          .build());

          4.8 预取号和打开授权页回调接口

          回调结果在如下对象接口中回调:

          new HTSSOManager.IHTSSOLoginListener () {
                      @Override
                      public void onFinish(String info) {
                      }
                  });

          参数说明:

          (1)String info:回调登录结果json字符串。

          (2)结果json内容及含义

          参数 类型 说明
          “0” int 主状态码,见“状态码说明”
          “1” int 副状态码,见“状态码说明”
          “2” String 运营商标识,“1”:移动,“2”:联通,“3”:电信,“-1”:无法获取运营商标识
          3 String 登录结果,登录成功时为json格式,登录失败时为提示信息。

          (3). 登录成功json内容及含义:

          参数 类型 说明
          “data” String 主状态码,见“状态码说明”
          “errno” String 提示内容,登录成功为空。
          “msg” String 运营商标识,“1”:移动,“2”:联通,“3”:电信,“-1”:无法获取运营商标识
          “request_id“ String 请求id,用于排查问题

          5.登录授权页说明

          5.1 授权页整体设计说明

          image.png

          5.2 授权页配置说明

          5.2.1 授权页状态栏

          主状态码说明

          方法 参数说明 说明
          setStatusBarColor int 设置状态栏颜色,Android5.0以上系统版本支持
          setLightColor boolean 设置状态栏文字颜色,true为黑色,Android6.0以上系统版本支持

          5.2.2 授权页导航栏

          方法 参数说明 说明
          setNavBackgroudColor int 设置导航栏背景颜色
          setNavHeight int 设置导航栏高度,单位dp
          setNavLineHeight int 设置导航栏底部分割线高度,单位dp
          setNavLineColor int 设置导航栏底部分割线颜色
          setNavReturnImageLeft boolean 设置导航栏返回键是否位于左边,如果为否则会设置在右边
          setNavReturnImagePath String 设置导航栏返回键图片地址,如在drawable-xhdpi/back.png,则直接调用setNavReturnImagePath("back")即可
          setNavTextColor int 设置导航栏标题颜色
          setNavTextSize int 设置导航栏标题字体大小, 单位sp
          setNavTitle String 设置导航栏标题
          方法 参数说明 说明
          setLogoWidth int 设置logo图片宽度,单位dp
          setLogoHeight int 设置logo图片高度,单位dp
          setLogoMarginLeft int 设置logo图片左边距,单位dp
          setLogoMarginRight int 设置logo图片右边距,单位dp
          setLogoOffsetY int 设置logo图片距离窗口顶部边距,单位dp
          setLogoOffsetYB int 设置logo图片距离窗口底部边距,单位dp
          setLogoImagePath String 设置logo图片地址,如在drawable-xhdpi/logo.png,setLogoImagePath("logo")即可
          setLogoShowState boolean 设置是否显示logo图片

          5.2.4 授权页号码区域

          方法 参数说明 说明
          setNumFieldOffsetY int 设置号码区域距离窗口顶部边距,单位dp
          setNumFieldOffsetYB int 设置号码区域距离窗口底部边距,单位dp
          setNumberSize int 设置号码文字大小,单位sp

          5.2.5 授权页授权按钮

          方法 参数说明 说明
          setLogBtnSize int,int 设置授权按钮大小,单位dp
          setLogBtnMargin int,int 设置授权按钮左右边距,单位dp
          setLogBtnOffsetY int 设置授权按钮距离窗口顶部边距,单位dp
          setLogBtnOffsetYB int 设置授权按钮距离窗口底部边距,单位dp
          setLogBtnImagePath String 设置授权按钮图片地址,如在drawable/btn_selector.xml,setLogBtnImagePath("btn_selector")即可
          setLogBtnText String 设置授权按钮文字
          setLogBtnTextColor String 设置授权按钮文字颜色

          5.2.6 授权页条款区域

          方法 参数说明 说明
          setPrivacyOffsetY int 设置条款区域距离窗口顶部边距,单位dp
          setPrivacyOffsetYB int 设置默认是否同意授权
          setPrivacyState boolean 设置条款区域左右边距
          setPrivacyMargin int,int 设置条款区域左右边距,单位dp
          setPrivacyAlignment() String,String, String,String,String 设置条款整体文案以及自定义条款和自定义条款的URL,最多支持2个自定条款
          setClauseColor() int,int 设置条款整体文字颜色和条款颜色
          setCheckedImagePath String 设置checkbox选中时图片地址,如在drawable-xhdpi/checked.png,setCheckedImagePath("checked")
          setUncheckedImagePath int, int 设置条款checkbox大小,单位dp

          5.2.7 授权页slogan区域

          方法 参数说明 说明
          setSloganOffsetY int 设置slogan区域距离窗口顶部边距,单位dp
          setSloganOffsetYB int 设置slogan区域距离窗口底部边距,单位dp
          setSloganTextSize int 设置slogan文字大小
          setSloganTextColor int 设置slogan文字颜色

          5.2.8 授权页整体

          方法 参数说明 说明
          setThemeId int 设置Theme ID
          setAuthPageWindowSize Int,int 设置认证窗口大小,单位dp
          setAuthPageWindowOffset Int,int 设置认证窗口偏移,单位dp
          setAuthPageAnim String,String 设置跳转到认证窗口的进入动画及退出动画,设置animation的名字,如fade_in.xml, 则设置为“fade_in”即可

          注意:

          授权页默认界面均未适配手机横屏,如果您的targetSDK >= 26时,当使用默认授权页时,需要将当前页面设置为方向设置为强制竖屏,如果您的targetSdk < 26时,将SDK内置授权页的方向强制为竖屏,此处主要是Android8.0机器,透明强制竖屏界面有一个系统bug。

          6.返回状态码说明

          返回状态码分为主状态码和副状态码两部分,主状态码用于区分各主要流程执行状态。副状态码用于具体流程中的具体执行状态。

          6.1 主状态码说明

          返回主状态码 主状态说明
          0 成功执行一键登录
          1 设备风险验证状态码
          2 运营商sdk返回状态码
          3 号码认证sdk执行状态码
          4 号码认证服务端响应码

          6.2 副状态码说明

          1. 当主状态码为0时:
          返回副状态码 副状态说明
          0 成功执行一键登录
          1. 当主状态码为1时:
          副状态码 副状态码说明
          999 该设备存在风险
          1. 当主状态码为2时:
          副状态码 副状态码说明
          移动、电信SDK返回状态码 见附录移动、电信运营商状态码说明
          1. 当主状态码为3时:
          返回副状态码 副状态码说明
          2001 号码认证SDK未初始化
          2002 宿主未集成运营一键登录SDK
          2003 当前设备无网络连接
          2004 当前设备无运营商sim卡
          2006 当前宿主无运营商配置信息
          2008 当前宿主运营商不支持一键登录
          2009 未知错误
          998 当前用户正在登陆
          2016 运营商SDK版本错误
          2017 用户取消授权
          1. 当主状态码为4时:
          返回副状态码 副状态码说明
          2005 号码认证服务端返回信息为空
          2010 参数错误
          2011 应用未配置或已停用
          2012 token转号码错误
          2013 号码获取uid错误
          2014 uid 获取小程序信息错误
          2015 附带号码请求风控失败

          7.附录

          7.1 移动一键登录SDK状态码

          状态码 说明
          103000 成功
          102507 登录超时(授权页点登录按钮时)
          103101 请求异常
          103102 包签名错误(社区填写的appid和对应的包名包签名必须一致)
          103111 错误的运营商请求(可能是用户正在使用代理或者运营商判断失败导致)
          103119 appid不存在
          103211 其他错误,联系技术支撑解决问题
          103412 无效的请求(1.加密方式错误;2.非json格式;3.空请求等)
          103414 参数校验异常
          103511 服务器ip白名单校验失败
          103811 token为空
          103902 scrip失效(短时间内重复登录)
          103911 token请求过于频繁,10分钟内获取token且未使用的数量不超过30个
          104201 token已失效或不存在(重复校验或失效)
          105001 联通取号失败
          105002 移动取号失败
          105003 电信取号失败
          105012 不支持电信取号
          105013 不支持联通取号
          105018 token权限不足(使用了本机号码校验的token获取号码)
          105019 应用未授权(未在开发者社区勾选能力)
          105021 当天已达取号限额
          105302 appid不在白名单
          105312 余量不足(体验版到期或套餐用完)
          105313 非法请求
          200005 用户未授权(READ_PHONE_STATE)
          200010 无法识别sim卡或没有sim卡(android)
          200015 短信验证码格式错误
          200020 用户取消登录
          200021 数据解析异常
          200022 无网络
          200023 请求超时
          200024 数据网络切换失败
          200025 未知错误一般出现在线程捕获异常,请配合异常打印分析
          200026 输入参数错误
          200027 未开启数据网络或网络不稳定
          200028 网络异常
          200038 异网取号网络请求失败
          200039 异网取号网关取号失败
          200040 UI资源加载异常
          200048 用户未安装sim卡
          200050 EOF异常
          200060 切换账号(未使用SDK短验时返回)
          200072 CA根证书校验失败
          200080 本机号码校验仅支持移动手机号
          200082 服务器繁忙
          200087 授权页成功调起

          7.2 电信一键登录SDK状态码

          状态码 说明
          0 请求成功
          -64 permission-denied(无权限访问)
          -65 API-request-rates-Exceed-Limitations(调用接口超限)
          -10001 取号失败
          -10002 参数错误
          -10003 解密失败
          -10004 ip受限
          -10005 异网取号回调参数异常
          -10006 Mdn取号失败,且属于电信网络
          -10007 重定向到异网取号
          -10008 超过预设取号阈值
          -10009 时间戳过期
          -20005 sign-invalid(签名错误)
          -20006 应用不存在
          -20007 公钥数据不存在
          -20100 内部解析错误
          -20102 加密参数解析失败
          -30001 时间戳非法
          -30003 topClass失效
          51002 参数为空
          51114 无法获取手机号数
          80000 请求超时
          80001 请求网络异常
          80002 响应码错误
          80003 无网络连接
          80004 移动网络未开启
          80005 Socket超时异常
          80006 域名解析异常
          80007 IO异常
          80008 No route to host
          80009 nodename nor servname provided, or not known
          80010 Socket closed by remote peer
          80100 登录结果为空
          80101 登录结果异常
          80102 预登录异常
          80103 SDK未初始化
          80104 未调用预登录接口
          80105 加载 nib 文件异常
          80200 用户关闭界面
          80201 其他登录方式
          80800 WIFI 切换异常
          80801 WIFI 切换超时

          7.3 联通一键登录SDK状态码

          状态码 说明
          0 请求成功
          101001 授权码不能为空
          101002 认证的手机号不能为空
          101003 UiConfig 不能为空
          101004 ApiKey 或 PublicKey 不能为空
          101005 超时
          101006 公钥出错
          101007 用户取消登录
          102001 选择流量通道失败
          201001 操作频繁请,请稍后再试
          302001 SDK 解密异常
          302002 网络访问异常
          302003 服务端数据格式出错