概述与资源

本文是OneLogin Android SDK的部署文档,用于指导OneLogin Android SDK的集成,读者需具有一定Android编程知识基础。

环境需求

条目 资源
开发目标 移动/电信支持Android 4.0以上,联通支持Android 5.0以上
开发环境 Android Studio 2.1.3
系统依赖 v7包
sdk三方依赖 com.cmic.sso.sdkcom.unicom.xiaowo.logincn.com.chinatelecom.account.api
包增量 0.97M
网络制式 移动2G/3G/4G,联通3G/4G,电信4G(2G/3G网络下时延相对较高,成功率相对较低)
网络环境 打开蜂窝数据流量并且给予应用蜂窝数据权限

相关开发资料

条目 资源
产品结构流程 交互流程通讯流程
接口文档 onelogin-android-api-docs
错误码 Error Code 列表

接入流程

注册账号

访问极验管理后台,按照步骤注册极验账号,若已注册可直接登录。进入【身份认证】模块,若无此模块权限,可联系您的专属极验商务开通权限。

创建应用

在极验管理后台【OneLogin–设置】中,提交您的APP信息生成一组APPID和APPKEY,IOS、Android APP支持共用一组APPID和APPKEY。

由于一键登录过程会对APP包名等信息进行校验,因此每新增一个应用或修改原有信息均需在管理后台重新提交审核。集成时需注意检查APPID和包名/包签名的一致性,不一致情况SDK会返回错误码。

快速体验Demo

Android压缩包附带的demo文件夹中是极验的示例工程,使用Android Studio打开示例工程,直接运行起来即可进行快速体验测试。也可完成以下配置步骤进行本地测试:

1、将包名修改成对应的测试包名;

2、将签名配置改成您的签名配置;

3、将APPID换成您在极验管理后台创建生成的信息(需注意APPID和包名/包签名的一致性)。

业务逻辑流程

流程概述

极验OneLogin 安卓SDK主要业务逻辑如下:

  • 1、预取号

    • a)获取脱敏手机号,为拉起授权页做准备。预取号成功之后方可拉起授权页。

    • b)建议在执行拉起授权页方法前,提前一段时间调用预取号方法以获得最佳用户体验(预取号需要1-3s时间),比如放在应用启动或进入登录页的前一个页面时调用。另外用户登出时也是调用该方法的时机。

    • c)预取号有效期电信/移动 1小时,联通10分钟。

    • d)建议先判断用户登录状态再决定是否调用预取号方法,已登录状态用户无需调用该方法。

  • 2、拉起授权页面

    • a)预取号成功之后方可调用该方法拉起授权页,调用该方法前建议先通过isPreGetTokenSuccess()方法判断预取号成功状态。

接口调用逻辑

极验OneLogin安卓SDK提供两种接口调用方式实现一键登录:

  • 1、预取号和授权页拉起时机均由开发者自主控制。使用此调用逻辑,开发者需自主处理预取号的时机和超期重试的逻辑等。具体调用步骤如下:

    • a)init() 初始化SDK

    • b)preGetToken() 预取号(应用启动或进入登录页的前一个页面、用户登出时是调用该方法的时机,预取号超期等逻辑需开发者自主处理)

    • c)requestToken() 拉起授权页面(调用该方法前建议先判断预取号是否成功)

  • 2、预取号逻辑封装在SDK内部,开发者只需控制授权页拉起时机。SDK内部处理预取号的逻辑,包括预取号超期后的重新预取号,以及弱网状态下的重试等。

    • a) init() 初始化SDK

    • b)register() 注册APPID(用户登出后建议再次调用该方法,以方便下次登录可直接拉起授权页面)

    • c)requestToken() 拉起授权页面

开发流程

远程依赖

implementation 'com.geetest.android:onelogin:0.9.0'

获取 SDK 及 Demo

点击下载

导入 SDK 到项目工程并配置开发环境

  1. 在 Demo 的libs包下,将获取的.aar文件拖拽到工程中的 libs 文件夹下。

  2. 在拖入.aar到 libs 文件夹后,还要检查.aar是否被添加到Library,要在项目的build.gradle下添加如下代码:

    repositories {
    flatDir {
    dirs 'libs'
    }
    }
  3. 手动将aar包添加依赖:

    implementation(name: 'geetest_onelogin_android_vx.y.z', ext: 'aar')

配置接口

开发者集成客户端 SDK 前,必须先在您的服务器上搭建相应的服务端获取登录信息的接口,并配置从极验后台获取的AppID。这里以服务端配置成功,客户端开发步骤为例,如下:

预取号和授权页拉起时机均由开发者自主控制:

  1. 配置初始化接口并自动实现预取号

    OneLoginHelper
    .with()
    .init(this);
  2. 设置调用界面的横竖屏,可以自主设置,也可以由sdk设置

    OneLoginHelper
    .with()
    //第一个参数为所需要配置的App_ID
    //第二个参数为预取号超时时间
    //第三个参数为所需实现监听回调结果接口
    .preGetToken(APP_ID, 5000, oneLoginListener);
  3. 调用取号接口

    OneLoginHelper
    .with()
    //第一个参数为自定义的全局配置接口
    //第二个参数为所需实现监听回调结果接口
    .requestToken(oneLoginThemeConfig, oneLoginListener);

预取号逻辑封装在SDK内部,开发者只需控制授权页拉起时机:

  1. 配置初始化接口并自动实现预取号

    OneLoginHelper
    .with()
    .init(this)
    //第一个参数为所需要配置的App_ID
    .register(APP_ID);
  2. 设置调用界面的横竖屏,可以自主设置,也可以由sdk设置

    OneLoginHelper
    .with()
    //第一个参数为当前页面
    //第二个参数为是否是竖屏
    .setRequestedOrientation(MainActivity.this, true);
  3. 调用取号接口

    OneLoginHelper
    .with()
    //第一个参数为自定义的全局配置接口
    //第二个参数为所需实现监听回调结果接口
    .requestToken(oneLoginThemeConfig, oneLoginListener);

集成代码参考下方的代码示例。更进一步的示例,见相关 Demo。

代码示例

初始化与校验

初始化

在项目的ApplicationonCreate方法里面进行初始化。

OneLoginHelper
.with()
.init(this)
.register(APP_ID);

配置当前页面是否是竖屏

OneLoginHelper
.with()
.setRequestedOrientation(MainActivity.this, true);

取号并获取免密登录 token 并使用 token 获取用户登录信息

获取 token 后,通过接口进行校验,并获取登录信息。

OneLoginHelper
.with()
.requestToken(new OneLoginThemeConfig.Builder().build(), new AbstractOneLoginListener() {
@Override
public void onResult(JSONObject jsonObject) {
try {
int statusResult = jsonObject.getInt("status");
if (statusResult == 200) {
new Thread(new Runnable() {
@Override
public void run() {
JSONObject jsonObject = new JSONObject();
try {
jsonObject.put("process_id", jsonObject.getString("process_id"));
jsonObject.put("token", jsonObject.getString("token"));
jsonObject.put("authcode", jsonObject.optString("authcode"));
} catch (JSONException e) {
e.printStackTrace();
}
String result = HttpUtils.requestNetwork(<---获取用户登录信息的接口--->, jsonObject);
}
}).start();
} else {
Toast.makeText(getApplicationContext(), jsonObject.toString(), Toast.LENGTH_SHORT).show();
}
} catch (JSONException e) {
e.printStackTrace();
}
}
});

关闭授权页

在关闭授权页的时候执行此方法。

OneLoginHelper
.with()
.quitAuthActivity();

日志打印

SDK提供部分日志,TAG为Geetest_OneLogin,移动运营商TAG为CMCC,电信运营商TAG为CT_,联通运营商TAG为uniaccount

常见问题


Q 1. 全机型,全系统兼容吗?

S : 本产品依赖第三方运营商SDK,联通SDK最低可兼容Android 5.0,因此移动、电信用户最低可支持Android 4.0,联通用户最低可支持Android 5.0


Q 2. 只有一个回调,该怎样处理页面切换等逻辑呢?

S :页面的所有状态都有错误码输出,可以根据错误码来实现。


Q 3. 怎样控制关闭授权页的时机?

S :在requestToken()方法执行完成之后,根据错误码来自主实现关闭授权页的时机,当请求成功之后需要页面跳转的时候是关闭授权页的时机。开发者自定义控件的事件发生时也是关闭授权页的时机。


Q 4. 授权页面的沉浸式状态栏或者设置状态栏的颜色怎么实现呢?

S :在0.6.1版本之后,可以通过setStatusBar方法设置。


Q 5. OneLogin与OnePass一起使用包冲突错误怎么解决?

S :在OnePass的demo中有具体的脚本实现,详见OnePass项目。


Q 6. 怎样实现横屏呢?

S :在页面初始化时调用OneLoginHelper.with().setRequestedOrientation(MainActivity.this, false)即可。然后页面的偏移量可以在OneLoginThemeConfig中进行配置。


Q 7. 怎样设置主题?

S :在清单文件中的activity中进行相关配置。0.9.0版本之后,需要在清单文件中添加:

<activity
android:name="com.geetest.onelogin.activity.OneLoginActivity"
tools:replace="android:theme"
android:theme="@style/Theme.ActivityDialogStyle" />
<activity
android:name="com.geetest.onelogin.activity.OneLoginWebActivity"
tools:replace="android:theme"
android:theme="@style/Theme.ActivityDialogStyle" />


Q 8. 如何设置授权页面的Logo?

S :在0.6.1版本之后,可以通过setLogoImgView方法设置。


Q 9. 怎样隐藏返回图标?

S :在0.6.1版本之后,可以通过setAuthNavReturnImgView方法设置。


Q 10. 怎样实现第三方登录的自定义?

S :在Demo中有详细的方法展示,在这里展示部分代码。

private void initLogin() {
LayoutInflater inflater1 = LayoutInflater.from(context);
RelativeLayout relativeLayout = (RelativeLayout) inflater1.inflate(R.layout.relative_item_view, null);
RelativeLayout.LayoutParams layoutParamsOther = new RelativeLayout.LayoutParams(RelativeLayout.LayoutParams.WRAP_CONTENT, RelativeLayout.LayoutParams.WRAP_CONTENT);
layoutParamsOther.setMargins(0,dip2px(context, 430), 0, 0);
layoutParamsOther.addRule(RelativeLayout.CENTER_HORIZONTAL);
relativeLayout.setLayoutParams(layoutParamsOther);
ImageView weixin = relativeLayout.findViewById(R.id.weixin);
ImageView qq = relativeLayout.findViewById(R.id.qq);
ImageView weibo = relativeLayout.findViewById(R.id.weibo);
weixin.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
Toast.makeText(context, "微信登录", Toast.LENGTH_SHORT).show();
}
});
qq.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
Toast.makeText(context, "qq登录", Toast.LENGTH_SHORT).show();
}
});
weibo.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
Toast.makeText(context, "微博登录", Toast.LENGTH_SHORT).show();
}
});
OneLoginHelper.with().addOneLoginRegisterViewConfig("title_button", new AuthRegisterViewConfig.Builder()
.setView(relativeLayout)
.setRootViewId(AuthRegisterViewConfig.RootViewId.ROOT_VIEW_ID_BODY)
.setCustomInterface(new CustomInterface() {
@Override
public void onClick(Context context) {
Toast.makeText(context, "动态注册的其他按钮", Toast.LENGTH_SHORT).show();
}
})
.build()
);
}


Q 11. 怎样设置弹窗形式?

S :在0.6.1版本之后,可以通过setDialogTheme方法设置。0.9.0版本之后,如果不改theme,则只需要这一步即可。


Q 12. 授权页面弹框背景为黑色,如何设置为透明?

S :授权页面以对话框形式弹出时,支持通过主题设置背景样式。未设置主题的情况下,默认背景为黑色,可参考以下方式设置为透明背景:

在主题配置文件styles.xml中增加对话框主题样式:

<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>

在AndroidManifest.xml中给授权页面应用主题样式(参考问题7):

<activity
android:name="com.geetest.onelogin.activity.OneLoginActivity"
...
android:theme="@style/Theme.ActivityDialogStyle" />


Q 13. OneLoginThemeConfig使用注意事项?

S :注意事项:

  1. 配置项的图片,地址都应为drawable目录下。
  2. OffsetY与OffsetY_B两者必须有一个值为0,偏移量以不为0的方向作为基准。

附录

客户端集成插件(除了原生的Android SDK 之外,OneLogin提供主流的开发工具集成插件)

React Native:https://github.com/GeeTeam/gt-onelogin-rn-example

Flutter:https://github.com/GeeTeam/gt-onelogin-flutter-example