概述与资源
本文是 OneLogin Android SDK 的部署文档,用于指导 OneLogin Android SDK 的集成,读者需具有一定 Android 编程知识基础。
1、环境需求
条目 | 资源 |
---|---|
开发目标 | 移动/电信支持 Android 4.0 以上,联通支持 Android 5.0 以上 |
开发环境 | Android Studio 2.1.3 |
Gradle 版本 | 3.3.0 以上 |
SDK 三方依赖 | com.cmic.sso.sdk 、com.unigeetest 、cn.com.chinatelecom.account |
包增量 | 0.83M |
网络制式 | 移动 2G/3G/4G/5G,联通 3G/4G/5G,电信 4G/5G(2G/3G 网络下时延相对较高,成功率相对较低) |
网络环境 | 打开蜂窝数据流量并且给予应用蜂窝数据权限 |
2、相关开发资料
条目 | 资源 |
---|---|
产品结构流程 | 交互流程,通讯流程 |
常见问题 | 常见问题 |
SDK 资源包 | 点击下载 |
SDK 当前版本 | 2.3.5.2 (Tips:0.8.0(不含)以下版本升级到该版本,服务端接口必须一同调整,否则会导致电信取号失败) |
准备工作
1、创建应用
登录极验后台创建应用获取APPID
和APPKEY
,具体步骤可参照账号创建。
2、快速体验 Demo
Android 压缩包附带的 demo 文件夹中是极验的示例工程,使用 Android Studio 打开示例工程,直接运行起来即可进行快速体验测试。
如果开发者需要将 SDK 集成到自己的项目进行体验,可完成以下配置步骤进行本地测试:
将包名修改成对应的测试包名;
将签名配置改成您的签名配置;
将
APPID
换成您在极验管理后台创建生成的信息(需注意APPID
和包名/包签名的一致性);参照服务端接入文档完成服务端接口的对接,注意客户端
APPID
与服务端保持一致。如未完成该步骤则仅能体验APP端功能,不能获取真实手机号。
3、开发环境搭建
3.1、gradle 集成
implementation 'com.geetest.android:onelogin:2.3.5.2' |
注:当前仅支持jcenter仓库的远程依赖,如果项目中只添加了maven中央仓库,会导致远程依赖失败,请在项目根目录的
build.gradle
中添加一下jcenter仓库
allprojects { |
3.2、手动集成
导入 SDK 到项目工程并配置开发环境
在
sdk
目录下,将获取的.aar
文件拖拽到工程中的 libs 文件夹下。在拖入
.aar
到 libs 文件夹后,还要检查.aar
是否被添加到Library,要在项目的 build.gradle 下添加如下代码:repositories {
flatDir {
dirs 'libs'
}
}手动将aar包添加依赖:
implementation(name: 'geetest_onelogin_android_vx.y.z', ext: 'aar')
AndroidManifest.xml 权限配置
SDK 已默认配置必要的权限以及内部 Activity 声明,正常情况下直接集成即可。
必要的权限包含:
<uses-permission android:name="android.permission.INTERNET" /> |
可选配的权限:
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> |
Android 6.0 以后 READ_PHONE_STATE 权限需要动态申请才有效,SDK 默认配置,如需该权限,请在应用内动态申请。SDK 使用 READ_PHONE_STATE 权限主要用于取号阶段判断当前开启数据流量的 SIM 卡是否与预取号阶段开启数据流量的 SIM 卡一致,提升取号的成功率,建议开发者申请本权限。未申请该权限不影响 SDK 正常取号功能。
权限说明:
权限名称 | 权限说明 | 使用说明 |
---|---|---|
INTERNET | 允许应用程序联网 | 用于访问极验、运营商网关和认证服务器 |
ACCESS_WIFI_STATE | 允许访问 WiFi 网络状态信息 | 允许 SDK 获取 WiFi 网络状态与连接信息 |
ACCESS_NETWORK_STAT | 允许访问网络状态 | 允许 SDK 判断当前网络处于移动网络或WiFi网络 |
CHANGE_NETWORK_STATE | 允许改变网络连接状态 | 设备在WiFi跟数据双开时,允许 SDK 内部请求(仅用于网关取号的请求)强行走数据网络通道 |
CHANGE_WIFI_STATE | 允许改变 WiFi 网络连接状态 | 设备在 WiFi 跟数据双开时,切允许 SDK 内部请求(仅用于网关取号的请求)强行走数据网络通道 |
READ_PHONE_STATE | 允许读取手机状态 | SDK 取号阶段判断换卡、移动 SDK 判断双卡和换卡 (低概率使用场景,非必须权限) |
WRITE_SETTINGS | 允许读写系统设置项 | 低版本系统进行数据切换用到的权限,添加后可增加 WiFi+4G 下网络环境下的取号成功率,高版本系统以上可去除该权限 |
- 混淆配置:
SDK 的 aar 包已做混淆处理,两次混淆会导致不可预期的错误,默认情况下 aar 包内包含当前 SDK 的混淆配置,远端依赖或者本地 aar 依赖都能确保 SDK 不被二次混淆。如有解压 aar 包单独集成 jar 与 资源文件的需求,请务必将解压目录中的proguard.txt
文件内容拷贝到应用的混淆配置中,跳过对 SDK 的二次混淆操作。
如过使用了 andRes 进行资源混淆,请将 SDK 内部包含资源排除混淆,避免因找不到资源而报错。排除配置如下:
whiteList = [ |
OneLogin(一键登录)
进阶模式和常规模式是一键登录的两种调用逻辑,如无特别需求建议直接使用进阶模式,两模式不可混合调用。1、进阶模式
1.1、调用逻辑
预取号逻辑封装在 SDK 内部,开发者只需控制授权页拉起时机,无需关心预取号是否完成。SDK 内部处理预取号的逻辑,包括预取号超期后的重新预取号,以及弱网状态下的重试等。
init()
初始化 SDK 并配置APPID
register()
注册(应用启动或进入登录页的前一个页面、用户登出时是调用该方法的时机)requestToken()
拉起授权页面(调用该方法前可以调用isPreGetTokenResultValidate
判断预取号是否成功, 失败时可先加载自定义 loading 等待对话框)dismissAuthActivity()
关闭授权页面
register
方法内会自动进行预取号,如果应用启动就调用,建议先判断或者请求网络权限之后再调用,否则可能因为网络不可达导致预取号失败。另外建议register
与requestToken
方法不要同时调用,预留预取号一定的时间以及内部初始化。注:preGetToken 为常规逻辑预取号方法,请勿与进阶逻辑 register 混用
1.2、初始化
- 初始化
init
SDK 初始化接口init
,可放在 Application
的 onCreate
方法中进行初始化。
方法描述
public OneLoginHelper init(Context context); |
参数说明
参数 | 类型 | 说明 |
---|---|---|
context | Context | 上下文 |
appId | String | 极验后台配置唯一产品APPID ,请在官网申请, 注意与服务端保持一致 |
- 注册
register
方法描述
注册接口,可同init
方法一起放在 Application 的 onCreate
方法中进行注册,或者在登录页前一个页面初始化时调用;登录成功后 SDK 内部不再维护预取号的有效性,如果用户退出登录后,为了方便下次重新登录能快速拉起授权页,也可以重新调用register
进行预取号。
public void register(String appId) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
app_id | String | 极验后台配置唯一产品APPID ,请在官网申请, 如init 接口传了 appId 此处可传空值 |
timeout | int | 超时时间,单位:ms ,取值范围:1000~15000 ,默认5000 |
代码示例
OneLoginHelper |
1.3、拉起授权页
- 拉起授权页
requestToken
方法描述
在需要登录的地方调用requestToken
接口拉起一键登录授权页,待用户点一键登录授权后获取运营商token
,获取成功后即可请求服务端换取本机手机号码。
public void requestToken(OneLoginThemeConfig oneLoginThemeConfig, AbstractOneLoginListener listener) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
oneLoginThemeConfig | OneLoginThemeConfig | 自定义全局配置接口,用来配置授权页面 UI 样式 |
listener | AbstractOneLoginListener | 回调监听器,需要开发者自己实现 |
代码示例
取号并获取免密登录的 token,通过接口进行校验,并获取登录信息。
OneLoginHelper |
1.4、关闭授权页
- 关闭授权页
dismissAuthActivity
方法描述
用户主动关闭授权页。SDK 除了返回按钮触发关闭以外,默认是不 finsih 授权页的,需要开发者在回调结束后自行实现关闭授权页。
public void dismissAuthActivity() |
代码示例
OneLoginHelper.with().dismissAuthActivity(); |
2、常规模式
如无特别需求建议直接使用进阶模式, 常规模式集成步骤参考常规模式集成文档
授权页面 UI 修改
通过实例化 OneLoginThemeConfig 并进行自定义配置,完成授权页面 UI 的个性化设计,每次调用拉起授权页方法前必须先传入该实例,否则授权界面会展示异常。授权页 UI 设计规范如下:
1、创建实例
- 创建实例
OneLoginThemeConfig oneLoginThemeConfig = new OneLoginThemeConfig.Builder().build(); |
修改主题配置的方法请在build
方法调用之前调用,所有配置方法参考下文接口说明。
2、弹框模式设置
- 设置弹窗主题相关
setDialogTheme
方法描述
设置弹窗主题相关。
setDialogTheme(boolean isDialogTheme, int dialogWidth, int dialogHeight, int dialogX, int dialogY, boolean isDialogBottom, boolean isWebViewDialogTheme) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
isDialogTheme | boolean | 是否使用弹窗模式,true 为使用,false 为不使用 | false |
dialogWidth | int | 弹窗模式宽度,长宽的单位都为dp ,以下单位与之保持一致 |
300 |
dialogHeight | int | 弹窗模式高度 | 500 |
dialogX | int | 授权⻚弹窗X偏移量(以屏幕⼼为原点) | 0 |
dialogY | int | 授权⻚弹窗Y偏移量(以屏幕⼼为原点) | 0 |
isDialogBottom | boolean | 授权⻚弹窗是否贴于屏幕底部 true:显示到屏幕底部,dialogY 参数设置将⽆效 false:不显示到屏幕底部,以 dialogY 参数为准 | false |
isWebViewDialogTheme | boolean | 隐私页面是否使用弹窗模式 | false |
3、添加自定义控件
- 添加自定义控件
addOneLoginRegisterViewConfig
方法描述
在requestToken()
方法之前实现。允许开发者在授权页面titlebar
和body
添加自定义的控件
注意:自定义的控件不允许覆盖 SDK 默认的 UI。
// 2.1.4 版本废弃该方法,建议用后者 |
代码示例
OneLoginHelper.with().addOneLoginRegisterViewConfig(id, authRegisterViewConfig); |
参数说明
参数 | 类型 | 说明 |
---|---|---|
id | String | 开发者自定义控件名称 |
authRegisterViewConfig | AuthRegisterViewConfig | 配置开发者自定义控件的控件来源,位置和处理逻辑等 |
- 实例化 AuthRegisterViewConfig 自定义控件配置
接口描述
创建自定义控件配置
AuthRegisterViewConfig authRegisterViewConfig = new AuthRegisterViewConfig.Builder().build(); |
方法说明
方法名 | 传参类型 | 说明 |
---|---|---|
setView | View | 开发者传入自定义的控件,需要设置好控件的布局属性,SDK 只支持RelativeLayout 布局,控件位置请通过RelativeLayout.LayoutParams 配置指定,具体配置可参考 demo 示例代码 |
setRootViewId | int | 设置控件的位置。RootViewId.ROOT_VIEW_ID_TITLE_BAR 指标题栏RootViewId.ROOT_VIEW_ID_BODY 指授权页空白处 |
setCustomInterface | CustomInterface | 设置控件事件。CustomInterface 是一个接口,自定义实现点击方法 |
4、授权页面其他配置
- 设置授权页面背景
setAuthBGImgPath
方法描述
设置背景图片。
setAuthBGImgPath(String authBGImgPath) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
authBGImgPath | String | 设置背景图片。放在 drawable 文件下,以下背景图片路径与之保持一致 |
gt_one_login_bg |
- 设置授权页面视频背景
setAuthBgVideoUri
方法描述
设置授权页面视频背景。
setAuthBgVideoUri(String authBgVideoUri) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
authBgVideoUri | String | 视频背景 Uri 字符串。放在 raw 文件下,如:"android.resource://" + this.getPackageName() + "/" + R.raw.geetest_demo_video |
null |
- 状态栏设置
setStatusBar
方法描述
设置状态栏颜色、字体颜色。
setStatusBar(int statusBarColor, int navigationBarColor, boolean isLightColor) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
statusBarColor | int | 自定义状态栏背景颜色 | 0 |
navigationBarColor | int | 自定义底部导航栏背景颜色 | 0 |
isLightColor | boolean | 设置状态栏内容的颜色(只能黑白),true 为黑色,false 为白色 | false |
- 标题栏设置
setAuthNavLayout
方法描述
设置标题栏布局
setAuthNavLayout(int navColor, int authNavHeight, boolean authNavTransparent, boolean authNavGone) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
navColor | int | 标题栏颜色 | 0xFF3973FF |
authNavHeight | int | 标题栏高度 | 49 |
authNavTransparent | boolean | 标题栏是否透明 | true |
authNavGone | boolean | 标题栏是否隐藏,此处的隐藏为 View.GONE |
false |
- 标题栏文字设置
setAuthNavTextView
方法描述
设置标题栏中间文字相关
setAuthNavTextView(String navText, int navTextColor, int navTextSize, boolean navWebTextNormal, String navWebViewText, int navWebViewTextColor, int navWebViewTextSize) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
navText | String | 文字设置 | 一键登录 |
navTextColor | int | 字体颜色 | 0xFFFFFFFF |
navTextSize | int | 字体大小,单位为sp ,以下设置字体大小的单位与之保持一致 |
17 |
navWebTextNormal | boolean | 设置是否隐私条款页面的标题栏中间文字使用默认值,true 为使用navWebViewText,false为使用默认隐私条款的名字 | false |
navWebViewText | String | 隐私条款页面的标题栏中间文字 | 服务条款 |
navWebViewTextColor | int | 隐私条款页面的标题栏中间文字颜色 | 0xFF000000 |
navWebViewTextSize | int | 隐私条款页面的标题栏中间文字大小 | 17 |
- 标题栏字体设置
setAuthNavTextViewTypeface
方法描述
设置标题栏中间文字的字体相关
setAuthNavTextViewTypeface(Typeface navTextTypeface, Typeface navWebViewTextTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
navTextTypeface | Typeface | 标题栏的文字的字体 | Typeface.DEFAULT |
navWebViewTextTypeface | Typeface | 条款页面标题栏的文字的字体 | Typeface.DEFAULT |
- 标题栏返回按钮设置
setAuthNavReturnImgView
方法描述
设置标题栏返回按钮相关
setAuthNavReturnImgView(String returnImgPath, int returnImgWidth, int returnImgHeight, boolean returnImgHidden, int returnImgOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
returnImgPath | String | 返回按钮图片 | gt_one_login_ic_chevron_left_black |
returnImgWidth | int | 返回按钮图片宽度 | 24 |
returnImgHeight | int | 返回按钮图片高度 | 24 |
returnImgHidden | boolean | 返回按钮是否隐藏 | false |
returnImgOffsetX | int | 返回按钮图片距离屏幕左边X轴偏移量 | 12 |
returnImgOffsetY | int | 返回按钮图片距离标题栏顶部偏移量,可选配,不传该参数默认标题栏垂直居中 | 0 |
- 返回事件屏蔽设置
setBlockReturnEvent
方法描述
设置是否屏蔽返回键与返回按钮返回事件,屏蔽后仍然会发生对应的错误码回调,只是 SDK 默认不关闭授权页。
setBlockReturnEvent(boolean blockReturnKey, boolean blockReturnBtn) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
blockReturnKey | boolean | 是否屏蔽返回键返回事件 | false |
blockReturnBtn | boolean | 是否屏蔽返回按钮返回事件 | false |
注:2.3.1 以前版本升级到最新版本且配置了屏蔽返回事件后,注意修改 onResult 回调内针对
-20301
与-20302
错误码的处理,避免还是调用了 dismissAuthActivity。
- logo设置
setLogoImgView
方法描述
设置logo相关
setLogoImgView(String logoImgPath, int logoWidth, int logoHeight, boolean logoHidden, int logoOffsetY, int logoOffsetY_B, int logoOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
logoImgPath | String | logo 图片 | gt_one_login_logo |
logoWidth | int | logo 图片宽度 | 71 |
logoHeight | int | logo 图片高度 | 71 |
logoHidden | boolean | logo 是否隐藏 | false |
logoOffsetY | int | logo 相对于状态栏下边缘 y 偏移 | 125 |
logoOffsetY_B | int | logo 相对于底部 y 偏移 | 0 |
logoOffsetX | int | logo 相对于屏幕左边 x 轴偏移量,当为0时表示居中显示 | 0 |
- 号码显示设置
setNumberView
方法描述
设置号码相关
setNumberView(int numberColor, int numberSize, int numberOffsetY, int numberOffsetY_B, int numberOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
numberColor | int | 号码栏字体颜色 | 0xFF3D424C |
numberSize | int | 号码栏字体大小 | 24 |
numberOffsetY | int | 号码栏相对于标题栏下边缘 y 偏移 | 200 |
numberOffsetY_B | int | 号码栏相对于底部 y偏移 | 0 |
numberOffsetX | int | 号码栏相对于屏幕左边 x 轴偏移量,当为 0 时表示居中显示 | 0 |
- 号码字体设置
setNumberText
方法描述
设置号码栏富文本样式,配置后将使用该富文本填充脱敏手机号内容
setNumberText(CharSequence numberText) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
numberText | CharSequence | 号码栏的富文本内容, 参考TextView 的setText(CharSequence text) 方法 |
null |
注:富文本内容应该包含正确的脱敏手机号,且配置之前必须确保能拿到正确的脱敏手机号
- 号码字体设置
setNumberViewTypeface
方法描述
设置号码栏字体相关
setNumberViewTypeface(Typeface numberTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
numberTypeface | Typeface | 号码栏的文字的字体 | Typeface.DEFAULT |
- 切换账号视图设置
setSwitchView
方法描述
设置切换账号相关
setSwitchView(String switchText, int switchColor, int switchSize, boolean switchHidden, int switchOffsetY, int switchOffsetY_B, int switchOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
switchText | String | 切换账号文字 | 切换账号,默认情况下受背景大小限制,只能显示4个字,如遇显示不全,建议通过setSwitchViewLayout 调整背景大小试试 |
switchColor | String | 切换账号字体颜色 | 0xFF3973FF |
switchSize | int | 切换账号字体大小 | 14 |
switchHidden | boolean | 切换账号是否隐藏 | false |
switchOffsetY | int | 切换账号相对于标题栏下边缘 y 偏移 | 249 |
switchOffsetY_B | int | 切换账号相对于底部 y 偏移 | 0 |
switchOffsetX | int | 切换账号相对于屏幕左边 x 轴偏移量,当为0时表示居中显示 | 0 |
- 切换账号视图背景设置
setSwitchViewLayout
方法描述
设置切换账号背景图片与宽高相关
setSwitchViewLayout(String switchImgPath, int switchWidth, int switchHeight) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
switchImgPath | String | 切换账号背景图片 | 默认无背景 |
switchWidth | int | 切换账号背景宽度 | 80 |
switchHeight | int | 切换账号背景高度 | 25 |
- 切换账号字体设置
setSwitchViewTypeface
方法描述
设置切换账号字体相关
setSwitchViewTypeface(Typeface switchTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
switchTypeface | Typeface | 切换账号的文字的字体 | Typeface.DEFAULT |
- 登录按钮布局设置
setLogBtnLayout
方法描述
设置登录按钮布局
setLogBtnLayout(String logBtnImgPath, int logBtnWidth, int logBtnHeight, int logBtnOffsetY, int logBtnOffsetY_B, int logBtnOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
logBtnImgPath | String | 登录按钮背景图片 | gt_one_login_btn_normal |
logBtnWidth | int | 登录按钮宽度 | 268 |
logBtnHeight | int | 登录按钮高度 | 36 |
logBtnOffsetY | int | 登录按钮相对于标题栏下边缘 y 偏移 | 249 |
logBtnOffsetY_B | int | 登录按钮相对于底部 y 偏移 | 0 |
logBtnOffsetX | int | 登录按钮相对于屏幕左边 x 轴偏移量,当为0时表示居中显示 | 0 |
- 登录按钮文字设置
setLogBtnTextView
方法描述
设置登录按钮中间文字相关
setLogBtnTextView(String logBtnText, int logBtnColor, int logBtnTextSize) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
logBtnText | String | 文字设置 | 一键登录 |
logBtnColor | int | 文字颜色 | 0xFFFFFFFF |
logBtnTextSize | int | 文字大小 | 15 |
- 登录按钮文字字体设置
setLogBtnTextViewTypeface
方法描述
设置登录按钮中间文字的字体相关
setLogBtnTextViewTypeface(Typeface logBtnTextTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
logBtnTextTypeface | Typeface | 登录按钮中间的文字的字体 | Typeface.DEFAULT |
- 登录按钮可用状态随选择框选择状态变化设置
setLogBtnDisableIfUnChecked
方法描述
设置登录按钮在选择框未选择时禁用状态
setLogBtnDisableIfUnChecked(boolean disableBtnIfUnChecked) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
disableBtnIfUnChecked | boolean | 登录按钮是否在选择框未选择时自动禁用 | false |
- 登录加载视图设置
setLogBtnLoadingView
方法描述
设置loading图片相关
setLogBtnLoadingView(String loadingView, int loadingViewWidth, int loadingViewHeight, int loadingViewOffsetRight) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
loadingView | String | loading 图片地址 | umcsdk_load_dot_white |
loadingViewWidth | int | loading 图片宽度 | 20 |
loadingViewHeight | int | loading 图片高度 | 20 |
loadingViewOffsetRight | int | loading 图片距离登录框右边 x 轴偏移量 | 12 |
loadingViewOffsetY | int | loading 图片距离登录框 y 轴偏移量,可选配,不传该参数默认登录框垂直居中 | 0 |
- 标语设置
setSloganView
方法描述
设置 Slogan 相关
setSloganView(int sloganColor, int sloganSize, int sloganOffsetY, int sloganOffsetY_B, int sloganOffsetX) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
sloganColor | int | 设置 Slogan 字体颜色 | 0xFFA8A8A8 |
sloganSize | int | 设置 Slogan 字体大小 | 10 |
sloganOffsetY | int | 设置 Slogan 相对于标题栏下边缘 y 偏移 | 382 |
sloganOffsetY_B | int | 设置 Slogan 相对于底部 y 偏移 | 0 |
sloganOffsetX | int | 设置 Slogan 相对于屏幕左边 x 轴偏移量,当为0时表示居中显示 | 0 |
- 标语字体设置
setSloganViewTypeface
方法描述
设置 Slogan 文字的字体相关
setSloganViewTypeface(Typeface sloganTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
sloganTypeface | Typeface | Slogan 文字的字体 | Typeface.DEFAULT |
- 隐私栏布局设置
setPrivacyLayout
方法描述
设置隐私条款布局
setPrivacyLayout(int privacyLayoutWidth, int privacyOffsetY, int privacyOffsetY_B, int privacyOffsetX, boolean isUseNormalWebActivity) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyLayoutWidth | int | 设置隐私条款宽度,隐私条款大部分为字体,只规定宽度,高度自适应 | 256 |
privacyOffsetY | int | 设置隐私条款相对于标题栏下边缘 y 偏移 | 0 |
privacyOffsetY_B | int | 设置隐私条款相对于底部 y 偏移 | 18 |
privacyOffsetX | int | 设置隐私条款对于屏幕左边 x 轴偏移量,当为 0 时表示居中显示 | 0 |
isUseNormalWebActivity | boolean | 设置是否跳转到默认的隐私条款页面 | true |
注:
privacyOffsetY
与privacyOffsetY_B
两个偏移量必须有一个为0,否则优先采用privacyOffsetY_B
。
- 隐私栏勾选框设置
setPrivacyCheckBox
方法描述
设置隐私条款选择框相关
setPrivacyCheckBox(String unCheckedImgPath, String checkedImgPath, boolean privacyState, int privacyCheckBoxWidth, int privacyCheckBoxHeight) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
unCheckedImgPath | String | 设置未选中下按钮的图片地址 | gt_one_login_unchecked |
checkedImgPath | String | 设置选中下按钮的图片地址 | gt_one_login_checked |
privacyState | boolean | 设置选择框是否默认勾选 | true |
privacyCheckBoxWidth | int | 选择框图片宽度 | 9 |
privacyCheckBoxHeight | int | 选择框图片高度 | 9 |
privacyCheckBoxOffsetY | int | 选择框图片Y轴偏移,可选配 | 2 |
privacyCheckBoxMarginRight | int | 选择框图片右边距,可选配 | 0 |
- 隐私条款文字显示设置
setPrivacyClauseView
方法描述
设置隐私条款字体相关
setPrivacyClauseView(int baseClauseColor, int clauseColor, int privacyClauseTextSize) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
baseClauseColor | int | 设置隐私条款基础文字颜色 | 0xFFA8A8A8 |
clauseColor | int | 设置隐私条款协议文字颜色 | 0xFF3973FF |
privacyClauseTextSize | int | 设置隐私条款字体大小 | 10 |
- 隐私条款文字设置
setPrivacyTextView
方法描述
设置除了隐私条款其他的字体相关
setPrivacyTextView(String privacyTextViewTv1, String privacyTextViewTv2, String privacyTextViewTv3, String privacyTextViewTv4) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyTextViewTv1 | String | 设置隐私条款文字1 | 登录即同意 |
privacyTextViewTv2 | String | 设置隐私条款文字2 | 和 |
privacyTextViewTv3 | String | 设置隐私条款文字3 | 、 |
privacyTextViewTv4 | String | 设置隐私条款文字4 | 并使用本机号码登录 |
- 设置隐私栏文字的字体
setPrivacyClauseViewTypeface
方法描述
设置隐私栏文字的字体相关
setPrivacyClauseViewTypeface(Typeface privacyClauseBaseTypeface, Typeface privacyClauseTypeface) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyClauseBaseTypeface | Typeface | 隐私栏基础的文字的字体 | Typeface.DEFAULT |
privacyClauseTypeface | Typeface | 隐私条款的文字的字体 | Typeface.DEFAULT |
- 开发者隐私条款设置
setPrivacyClauseText
方法描述
设置开发者隐私条款相关。
自定义隐私条款顺序。按顺序设置,当有条款名称与条款 URL 一起为空时,则使用默认的运营商隐私条款。否则按照顺序排列,自定义隐私条款最多只能两个。
setPrivacyClauseText(String clauseNameOne, String clauseUrlOne, String clauseNameTwo, String clauseUrlTwo, String clauseNameThree, String clauseUrlThree) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
clauseNameOne | String | 设置隐私条款1名称 | null |
clauseUrlOne | String | 设置隐私条款1 URL | null |
clauseNameTwo | String | 设置隐私条款2名称 | null |
clauseUrlTwo | String | 设置隐私条款2 URL | null |
clauseNameThree | String | 设置隐私条款3名称 | null |
clauseUrlThree | String | 设置隐私条款3 URL | null |
- 开发者隐私条款设置
setPrivacyClauseTextStrings
方法描述
设置多个开发者隐私条款相关。
自定义多个隐私条款。按顺序设置,长度为 4 的倍数,配置后优先使用该接口的配置,否则使用setPrivacyClauseText
的配置。可通过预留一组空字符串配置让 SDK 自动添加运营商协议。
setPrivacyClauseTextStrings(String... privacyClauseTextStrings) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyClauseTextStrings | String[] | 设置隐私条款数组 | null |
代码示例
/** |
注:
运营商隐私协议必须显示,开发者需保留一组条款参数留空
- 隐私条款名称显示书名号相关
setPrivacyAddFrenchQuotes
方法描述
设置授权页面隐私条款名称显示书名号。
setPrivacyAddFrenchQuotes(boolean privacyAddFrenchQuotes) |
注: 个别第三方系统可能存在对包含中文字符的富文本渲染异常,出现文字超出控件右边界显示被截断的情况,建议不要添加书名号。
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyAddFrenchQuotes | boolean | 是否设置隐私条款名称显示书名号 | false |
- 隐私条款文字对齐方式
setPrivacyTextGravity
方法描述
设置隐私条款文字对齐方式。
setPrivacyTextGravity(int privacyTextGravity) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
privacyTextGravity | int | 设置隐私条款文字对齐方式,参考TextView.setGravity 方法 |
Gravity.TOP|Gravity.START |
- 隐私条款文字行间距
setPrivacyLineSpacing
方法描述
设置隐私条款文字行间距,参考TextView.setLineSpacing
方法。
setPrivacyLineSpacing(float lineSpacingExtra, float lineSpacingMultiplier) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
lineSpacingExtra | float | 设置隐私条款文字行间距,单位: dp | 8.0f |
lineSpacingMultiplier | float | 设置隐私条款文字行间距的倍数 | 1.0f |
- 未同意隐私条款时的文字提示
setPrivacyUnCheckedToastText
方法描述
设置未同意隐私条款时的文字提示相关。
setPrivacyUnCheckedToastText(String privacyUnCheckedToastText) |
参数说明
参数 | 参数类型 | 说明 | 默认值 |
---|---|---|---|
enableToast | boolean | 设置是否弹出 Toast 提示文字,可选配 | true |
privacyUnCheckedToastText | String | 设置未同意隐私条款的文字提示相关 | 请同意服务条款 |
其他接口说明
1、横竖屏设置
- 设置横竖屏
setRequestedOrientation
方法描述
设置授权页前个页面的方向,授权页默认通过android:screenOrientation="behind"
跟随前个页面的方向。该方法 2.3.0 以后版本废弃,建议直接在 AndroidManifest 中配置登录页前一个 Activity 的方向。
public void setRequestedOrientation(Activity activity, boolean isPortrait) |
代码示例
OneLoginHelper.with().setRequestedOrientation(MainActivity.this, true); |
参数说明
参数 | 类型 | 说明 |
---|---|---|
activity | Activity | 当前调用 OneLogin 的页面 |
isPortrait | boolean | 是否是竖屏 |
2、回调接口实现
通过实现AbstractOneLoginListener
接口,通过它的多个回调可获取预取号、拉起授权页取号时的各种返回状态与结果,每次调用拉起授权页方法前必须先传入该接口的实现,否则不能正常拉起授权页。
2.1、结果返回
方法描述
当前流程的结果返回。取号成功、取号失败、切换账号、点返回或者按返回键从授权页返回取消登录等都从该回调返回结果,具体请参考 OneLogin 返回码。
public onResult(JSONObject jsonObject) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
jsonObject | JSONObject | 回调信息 |
jsonObject 的参数说明
- 取号成功
参数名 | 必须 | 类型 | 说明 |
---|---|---|---|
msg |
是 | String | 运营商返回的状态信息 |
process_id |
是 | String | 流水号(有效期10分钟 ) |
app_id |
是 | String | 极验后台配置唯一 id |
operator |
是 | String | 客户端获取的运营商 |
clienttype |
是 | String | 客户端,1 表示 Android |
sdk |
是 | String | SDK 的版本号 |
status |
是 | int | 状态码,状态码为 200 |
token |
是 | String | 运营商返回的accessToken |
authcode |
否 | String | 电信运营商返回的authcode |
- 取号失败
参数名 | 必须 | 类型 | 说明 |
---|---|---|---|
errorCode |
是 | String | 错误码 |
msg |
是 | String | 运营商返回的状态信息 |
process_id |
是 | String | 流水号(有效期10分钟 ) |
app_id |
是 | String | 极验后台配置唯一 id |
metadata |
是 | JSONObject | 具体的错误原因 |
operator |
是 | String | 客户端获取的运营商 |
clienttype |
是 | String | 客户端,1 表示 Android |
sdk |
是 | String | SDK 的版本号 |
status |
是 | int | 状态码,状态码为 500 |
2.2、获取脱敏手机号
方法描述
获取用于界面展示的脱敏手机号
public void onRequestTokenSecurityPhone(String phone) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
phone | String | 脱敏手机号 |
2.3、隐私条款点击
方法描述
隐私条款点击回调
public void onPrivacyClick(String name, String url) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
name | String | 隐私条款名称 |
url | String | 隐私条款地址 |
2.4、登录按钮点击
方法描述
登录按钮点击回调
public void onLoginButtonClick() |
2.5、授权页面拉起
方法描述
授权页面拉起回调
public void onAuthActivityCreate(Activity activity) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
activity | Activity | 授权页面 |
2.6、隐私条款页面拉起
方法描述
隐私条款页面拉起回调
public void onAuthWebActivityCreate(Activity activity) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
activity | Activity | 隐私条款页面 |
2.7、隐私条款 CheckBox 点击
方法描述
CheckBox点击回调
public void onPrivacyCheckBoxClick(boolean isChecked) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
isChecked | boolean | CheckBox 是否选择 |
2.8、一键登录加载 loading
方法描述
点一键登录时弹出自定义对话框式 loading 时机
public void onLoginLoading() |
2.9、一键登录结合其他验证方式
方法描述
点一键登录时是否先调用其他验证方式进行验证
public boolean onRequestOtherVerify() |
参数说明
参数 | 类型 | 说明 | 默认值 |
---|---|---|---|
返回值 | boolean | 是否先调用其他验证方式进行验证 | false |
2.10、返回按钮点击
方法描述
点授权页面标题栏返回按钮或者手机返回键时的回调。
注: 该回调与带
-20301/-20302
返回码的onResult
回调共存,两者都会返回
public void onBackButtonClick() |
2.11、切换账号点击
方法描述
点授权页面切换账号栏的回调。
注: 该回调与带
-20303
返回码的onResult
回调共存,两者都会返回
public void onSwitchButtonClick() |
3、日志打印
- 日志打印控制
setLogEnable
方法描述
设置是否开启 SDK 日志打印功能,默认是开启的,开启后 SDK 运行过程中会打印以 Geetest_OneLogin 为 TAG 的 logcat 日志。正式上线应用可以调用该接口关闭日志。
public OneLoginHelper setLogEnable(boolean logEnable) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
logEnable | boolean | 是否开启日志 |
代码示例
OneLoginHelper.with().setLogEnable(false); |
注:开启日志后,Release 模式也会打印 SDK 内日志
4、预取号状态判断
- 取号是否有效
isPreGetTokenResultValidate
方法描述
判断是否预取号结果是否有效,预取号失败、预取号结果超期、预取号结果已使用情况均返回预取号结果失效。
public boolean isPreGetTokenResultValidate() |
代码示例
OneLoginHelper.with().isPreGetTokenResultValidate(); |
5、SDK 版本号
- 获取 SDK 版本号
sdkVersion
方法描述
获取 SDK 版本号
public void sdkVersion() |
代码示例
OneLoginHelper.with().sdkVersion() |
6、初始化状态判断
- 初始化是否成功
isInitSuccess
方法描述
判断是否初始化成功,cancel 之后必须重新初始化。
public boolean isInitSuccess() |
代码示例
OneLoginHelper.with().isInitSuccess(); |
7、隐私条款是否勾选
- 隐私条款是否勾选
isPrivacyChecked
方法描述
判断是否勾选同意隐私条款声明。
public boolean isPrivacyChecked() |
代码示例
OneLoginHelper.with().isPrivacyChecked(); |
8、关闭授权页加载动画
- 关闭授权页面的 loading
stopLoading
方法描述
关闭授权页面的 loading,在校验方法中实现
public void stopLoading() |
代码示例
OneLoginHelper.with().stopLoading(); |
9、隐私页 WebView 配置
- 配置隐私页 WebView 控件的 WebViewClient 属性
setWebViewClient
方法描述
配置隐私页 WebView 控件的 WebViewClient 属性,用以自定义处理 WebView 加载隐私后的事件回调
public void setWebViewClient(WebViewClient webViewClient) |
代码示例
OneLoginHelper.with().setWebViewClient(new WebViewClient() { |
10、行为验证 API 配置
- 一键登录接入行为验证的 API 配置
setCaptchaApi
方法描述
配置行为验证 API1、API2 与超时时间。行为验证属于我司其他产品,跟 OneLogin 无关联,不冲突,可以用来增强一键登录之前的人机校验功能。 API1 与 API2 说明请参考: https://docs.geetest.com/sensebot/overview/guide/operate
public void setCaptchaApi(String api1, String api2, int timeout) |
参数说明
参数 | 类型 | 说明 |
---|---|---|
api1 | String | 行为验证 API1 |
api2 | String | 行为验证 API2 |
timeout | int | 行为验证 API1 与 API2 请求超时时间 |
代码示例
OneLoginHelper.with().setCaptchaApi("https://www.geetest.com/demo/gt/register-slide", |
11、一键登录延迟取号
- 点一键登录后延迟取号
requestTokenDelay
方法描述
点击一键登录后,onRequestOtherVerify
回调返回 true, 先进行其他方式进行预校验,校验通过后通过该接口通知 SDK 进行取号
public void requestTokenDelay() |
代码示例
OneLoginHelper.with().requestTokenDelay(); |
12、安全功能配置
- 配置是否开启安全功能
setDeepKnowEnable
方法描述
一键登录 SDK 如果和 深知 Pro SDK 同时集成时,默认开启一键登录 SDK 内部安全功能,通过该接口可配置是否关闭 SDK 内安全功能。
public void setDeepKnowEnable(boolean enable) |
参数说明
参数 | 类型 | 说明 | 默认值 |
---|---|---|---|
enable | boolean | 是否开启安全功能 | true |
代码示例
OneLoginHelper.with().setDeepKnowEnable(false); |
13、SDK 内存清理
- 释放 SDK 所有内部引用
cancel
方法描述
一键登录结束后,如果不需要继续使用一键登录相关功能,可以调用 cancel 方法释放 SDK 内部的引用,减少内存泄漏。调用该方法后,如需再次登录,需要重新预取号。
public void cancel() |
注: 该方法会清理掉 SDK 内部核心单例并置空,导致部分缓存失效,部分接口耗时增加,建议酌情使用。
代码示例
OneLoginHelper.with().cancel(); |
- 释放 SDK 持有的 listener 引用
removeOneLoginListener
方法描述
一键登录结束后,可以调用removeOneLoginListener
释放preGetToken
与requestToken
传入的 listener 参数,防止 listener 持有外部类的引用导致内存泄漏。
public void removeOneLoginListener() |
代码示例
OneLoginHelper.with().removeOneLoginListener(); |
一键登录接入行为验证
一键登录 SDK 提供两种方式接入极验的行为验证能力,作为取号的辅助校验功能
1、SDK 内集成行为验证
SDK 内集成方式方便用户以极简的方式快速接入行为验证能力,简化接入难度。
1.1、集成步骤
1.2、集成说明
- SDK 可识别 API1 返回参数格式:
//success: 1 正常验证模式 |
- SDK 可识别 API2 返回参数格式:
//成功 |
2、应用内集成行为验证
应用内集成行为验证,方便用户进行充分的自定义行为验证 API1/API2、请求与响应,UI 配置等
2.1、集成步骤
请参考行为验证发布 demo 中的
Bind
模式接入行为验证重写一键登录的
onRequestOtherVerify
回调,在回调里启动行为验证,回调方法里返回true
行为验证验证通过后调用
requestTokenDelay
进行取号
OnePass(本机号码认证)
1、调用逻辑
init()
初始化 SDKgetToken()
获取手机号对应的Token
2、接口配置
- 初始化接口
//第二个参数为所需要配置的 APPID |
- 本机号校验接口
OnePassHelper.with().getToken(phone, onePassListener); |
- 回调实现接口
OnePassListener onePassListener = new OnePassListener() { |
3、示例代码
3.1、初始化
- 初始化
在项目的具体页面的onCreate
方法里面进行初始化。
// 参数一为 Activity 或者 Application 上下文 Context |
3.2、本机号校验
OnePassListener onePassListener = new OnePassListener() { |
3.3、关闭页面
在页面关闭的时候执行此方法。
|
4、其他接口说明
4.1、配置是否缓存手机号
- 配置 SDK 是否缓存手机号到本地
setCacheNumberEnable
方法描述
获取 token 之前调用该接口配置是否开启缓存手机号功能。配置开启后,每次调用getToken
方法时,会加密保存当前传入的手机号到本地配置,用于减少用户登录页重复输入手机号流程,提升登录效率;配置关闭时,则会清除本地缓存的手机号,并且调用getToken
方法时,不会记录手机号。
public OnePassHelper setCacheNumberEnable(boolean enable) |
注: 配置开启后,手机号仅加密缓存到本地,每次
getToken
后都会覆盖更新,不会搜集与上传。
参数说明
参数 | 类型 | 说明 | 默认值 |
---|---|---|---|
enable | boolean | 是否开启手机号缓存功能 | true |
代码示例
OnePassHelper.with().setCacheNumberEnable(true); |
4.2、获取缓存的手机号
- 获取本地缓存的手机号
getCachedNumber
方法描述
开启缓存手机号功能后,每次进入登录页面,可调用该方法获取上一次调用getToken
时缓存的手机号。未开启手机号缓存、首次调用、内部解密失败或其他异常时,返回结果为空字符串。
public String getCachedNumber() |
代码示例
String number = OnePassHelper.with().getCachedNumber(true); |
插件资源
客户端集成插件(除了原生的 Android SDK 之外,OneLogin 提供主流的开发工具集成插件)
React Native:https://github.com/GeeTeam/gt-onelogin-rn-example
Flutter:https://github.com/GeeTeam/gt-onelogin-flutter-example