> >

OneLogin (一键登录)


进阶模式和常规模式是一键登录的两种调用逻辑,如无特别需求建议直接使用进阶模式,两模式不可混合调用。

常规模式

预取号和授权页拉起时机均由开发者自主控制。使用此调用逻辑,开发者需自主处理预取号的时机和超期重试的逻辑等。使用这种方式时,请使用 OneLogin 类中的方法。

1、调用逻辑

  1. registerWithAppID: 初始化 SDK 并配置 APPID
  2. preGetTokenWithCompletion: 预取号(应用启动或进入登录页的前一个页面、用户登出时是调用该方法的时机)
  3. requestTokenWithViewController:viewModel:completion: 拉起授权页面(调用该方法前可以调用 isPreGettedTokenValidate 判断预取号是否成功)
  4. dismissAuthViewController:completion: 关闭授权页面

2、初始化

方法原型

/**
向SDK注册AppID

@discussion `AppID`通过后台注册获得,从极验后台获取该AppID,AppID需与bundleID配套

@param appID 产品ID
*/
+ (void)registerWithAppID:(NSString *)appID;

参数描述

参数 是否必填 类型 说明
appID NSString 极验 appID

接口作用

传入极验 appID,并开始预取号,注意客户端 AppID 需与服务端保持一致

使用场景

  • 保证在拉起授权页面前至少调用一次

  • 只需调用一次,多次调用不会多次初始化,与一次调用效果一致

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在 UIViewController 的 viewDidLoad 方法中添加初始化代码

- (void)viewDidLoad {
[super viewDidLoad];
// 设置AppId,AppID通过后台注册获得,从极验后台获取该AppID,AppID需与bundleID配套
[OneLogin registerWithAppID:GTOneLoginAppId];
}

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在 UIViewController 的 viewDidLoad 方法中添加初始化代码

override func viewDidLoad() {
super.viewDidLoad()
// 设置AppId,AppID通过后台注册获得,从极验后台获取该AppID,AppID需与bundleID配套
OneLogin.register(withAppID: GTOneLoginAppId)
}

3、预取号

方法原型

/**
预取号接口

@discussion 调用限制说明

在调用该方法后, 未回调之前, 再次调用该方法时, 方法会直接跳出, 不执行预取号逻辑。

@discussion 预取号成功后存在的有效期

有效期内需要调用 `requestTokenWithViewController:viewModel:completion:`,
否则需要重新访问 `preGetTokenWithCompletion:`。 其中中国移动和中国电信有效期为 1 小时,
中国联通为 10 分钟。

@param completion 处理回调
*/
+ (void)preGetTokenWithCompletion:(void(^)(NSDictionary *sender))completion;

参数描述

参数 是否必填 类型 说明
completion void(^)(NSDictionary * _Nullable sender) 获取临时凭证回调

回调的字段如下:

获取成功:
{
"model" : "iPhone9,1",
"accessCode" : "d3f3c605a2684a8fbb4b43ee0f94f1ff",
"operatorType" : "CU",
"release" : "13.5.1",
"processID" : "1f1437fd0b3026ff44500c3d03cdd822",
"appID" : "b41a959b5cac4dd1277183e074630945",
"pre_token_time" : "1087",
"number" : "186****6173",
"preGetTokenSuccessedTime" : 1604890389.0020308,
"msg" : "获取accessCode成功",
"status" : 200,
"expire_time" : 580
}

获取失败:
{
"status" : 500,
"operatorType" : "CU",
"appID" : "b41a959b5cac4dd1277183e074630945",
"model" : "iPhone9,1",
"release" : "13.5.1",
"msg" : "Can't access cellular.",
"errorCode" : "-20202"
}
字段 说明
status 状态码,200 表示成功,500 表示失败
number 脱敏手机号
operatorType 运营商
errorCode 获取失败时的错误码
msg 获取失败时表示失败原因

接口作用

可以提前获知当前用户的手机网络环境是否符合一键登录的使用条件,成功后将得到用于一键登录使用的临时凭证,默认的凭证有效期: 60 分钟(移动) / 60 分钟(电信) / 10 分钟(联通)

应用启动时或者进入登录页的前一个页面、用户登出时是调用该方法的时机

4、进入授权页面

方法原型

/**
进行用户认证授权, 获取网关 token 。

@discussion 调用限制说明

为避免授权页面多次弹出, 在调用该方法后, 授权页面弹出, 再次调用该方法时,
该方法会直接跳出, 不执行授权逻辑。

@discussion 需要用户在弹出的页面上同意服务意条款后, 才会进行免密认证。

@param viewController present 认证页面控制器的 vc
@param viewModel 自定义授权页面的视图模型
@param completion 结果处理回调

@seealso OLAuthViewModel

*/
+ (void)requestTokenWithViewController:(nullable UIViewController *)viewController
viewModel:(nullable OLAuthViewModel *)viewModel
completion:(void(^)(NSDictionary * _Nullable result))completion;

参数描述

参数 是否必填 类型 说明
viewController UIViewController 进入授权页面的上一级页面
viewModel OLAuthViewModel 授权页面UI配置参数
completion void(^)(NSDictionary * _Nullable result) 获取token回调

注意:
1、在成功进入授权页面时,不会立即收到 completion 回调,在授权页面点击一键登录、切换账号或者返回按钮时,才会收到 completion 回调;
2、若不能成功进入授权页面,则会立即收到 completion 回调

回调的字段如下:

获取成功:
{
"model" : "iPhone9,1",
"authcode" : "0000",
"operatorType" : "CU",
"release" : "13.5.1",
"processID" : "967ceb230b3fdfb4d74ebcb470c5830c",
"appID" : "b41a959b5cac4dd1277183e074630945",
"pre_token_time" : "1012",
"token" : "CU__0__b41a959b5cac4dd1277183e074630945__2.3.4__1__f632d01ab7c64efda96580c3274de971__NOTCUCC",
"number" : "186****6173",
"preGetTokenSuccessedTime" : 1604890895.807291,
"errorCode" : "0",
"msg" : "获取accessCode成功",
"status" : 200,
"expire_time" : 580
}

获取失败:
{
"status" : 500,
"operatorType" : "CU",
"appID" : "b41a959b5cac4dd1277183e074630945",
"model" : "iPhone9,1",
"release" : "13.5.1",
"msg" : "Can't access cellular.",
"errorCode" : "-20202"
}
字段 说明
status 状态码,200 表示成功,500 表示失败
token 换取手机号需要的 token
processID 流水号
authcode authcode
appID appID
operatorType 运营商
number 脱敏手机号
errorCode 失败时的具体错误码
msg 失败时表示失败原因

接口作用

拉起授权页面,用户在授权页面点击一键登录,即可获取 token,拿该 token 即可换取对应的手机号

调用该方法前建议先调用方法判断预取号是否成功

使用场景

  • 用户进行一键登录操作时调用该方法,如果初始化成功SDK 将会拉起授权页面

  • 可以在多处调用

  • 需在调用初始化方法之后且预取号成功之后

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在需要使用一键登录的地方调用极验一键登录接口

- (IBAction)normalLoginAction:(UIButton *)sender {
OLAuthViewModel *viewModel = [OLAuthViewModel new];
[OneLogin requestTokenWithViewController:self viewModel:viewModel completion:^(NSDictionary * _Nullable result) {
NSLog(@"OneLogin requestTokenWithViewController result: %@", result);
}];
}

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在需要使用一键登录的地方调用极验一键登录接口

@IBAction func normalLoginAction(_ sender: UIButton) {        
let viewModel = OLAuthViewModel()
// 进入授权页面
OneLogin.requestToken(with: self, viewModel: viewModel) { [weak self] result in
}
}

5、手动关闭授权页面

方法原型

/**
@abstract 关闭当前的授权页面

@param animated 是否需要动画
@param completion 关闭页面后的回调

@discussion
请不要使用其他方式关闭授权页面, 否则可能导致 OneLogin 无法再次调起
*/
+ (void)dismissAuthViewController:(BOOL)animated completion:(void (^ __nullable)(void))completion;

参数描述

参数 是否必填 类型 说明
animated BOOL 关闭授权页面时是否需要动画
completion void(^)(void) 关闭授权页面后的回调

接口作用

当开发者设置点击一键登录或者自定义控件不自动销毁授权页时,将需要自行调用此方法主动销毁授权页,建议在置换手机号成功后销毁,请不要使用其他方式关闭授权页面

关闭授权页面时机

  • 在授权页面点击切换账号按钮时

  • 在授权页面点击一键登录按钮收到 requestToken 结果回调之后

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在需要关闭授权页面的地方调用极验关闭授权页面接口

- (void)dismissAuthVC {
[OneLogin dismissAuthViewController:nil];
}

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 在需要关闭授权页面的地方调用极验关闭授权页面接口

@objc func dismissAuthVC(_ sender: UIButton) {
OneLogin.dismissAuthViewController {

}
}

6、判断预取号结果是否有效

方法原型

/**
* @abstract 预取号拿到的token是否还在有效期
*
* @return YES - 还在有效期,可直接调用requestTokenWithViewController方法进行取号
* NO - 已失效,需重新调用preGetTokenWithCompletion进行预取号之后再调用requestTokenWithViewController方法进行取号
*/
+ (BOOL)isPreGettedTokenValidate;

接口作用

判断预取号结果是否有效

调用时机

  • 调用requestTokenWithCompletion时,判断是否需要先调用preGetTokenWithCompletion

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 判断预取号结果是否有效

// 根据SDK的方法判断当前预取号结果是否有效,若当前预取号结果有效,则直接调用requestTokenWithViewController方法拉起授权页面,否则,先调用预取号方法进行预取号,预取号成功后再拉起授权页面
__weak typeof(self) wself = self;
if ([OneLogin isPreGettedTokenValidate]) {
[OneLogin requestTokenWithViewController:self viewModel:viewModel completion:^(NSDictionary * _Nullable result) {
NSLog(@"requestTokenWithViewController result: %@", result);
}];
} else {
[GTProgressHUD showLoadingHUDWithMessage:nil];
[OneLogin preGetTokenWithCompletion:^(NSDictionary * _Nonnull preResult) {
[GTProgressHUD hideAllHUD];
NSLog(@"preGetTokenWithCompletion result: %@", preResult);
if (preResult.count > 0 && preResult[@"status"] && 200 == [preResult[@"status"] integerValue]) {
[OneLogin requestTokenWithViewController:wself viewModel:viewModel completion:^(NSDictionary * _Nullable result) {
NSLog(@"requestTokenWithViewController result: %@", result);
// 自定义授权页面点击登录按钮之后的loading时,调用此方法会触发stopLoadingViewBlock回调,可以在此回调中停止自定义的loading
[OneLogin stopLoading];
[wself finishRequestingToken:result];
}];
} else { // 预取号失败
[GTProgressHUD showToastWithMessage:preResult[@"msg"]?:@"预取号失败"];
}
}];
}

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 判断预取号结果是否有效

// 根据SDK的方法判断当前预取号结果是否有效,若当前预取号结果有效,则直接调用requestTokenWithViewController方法拉起授权页面,否则,先调用预取号方法进行预取号,预取号成功后再拉起授权页面
if OneLogin.isPreGettedTokenValidate() {
OneLogin.requestToken(with: self, viewModel: viewModel) { [weak self] result in
if let strongSelf = self {
strongSelf.finishRequsetingToken(result: result!)
}
sender.isEnabled = true
}
} else {
GTProgressHUD.showLoadingHUD(withMessage: nil)
OneLogin.preGetToken { [weak self] preResult in
GTProgressHUD.hideAllHUD()
if let strongSelf = self {
let status = NSString.init(format: "%@", preResult["status"] as! NSNumber)
if 200 == status.integerValue {
OneLogin.requestToken(with: strongSelf, viewModel: viewModel) { (result) in
strongSelf.finishRequsetingToken(result: result!)
}
} else {
let message = (preResult["msg"] != nil) ? (preResult["msg"] as! String) : "预取号失败"
GTProgressHUD.showToast(withMessage: message)
}
}
sender.isEnabled = true
}
}

7、设置请求超时时间

方法原型

/**
分别设置预取号和取号请求超时时长。默认时长8s。

@param preGetTokenTimeout 预取号超时时长
@param requestTokenTimeout 取号超时时长
*/
+ (void)setRequestTimeout:(NSTimeInterval)preGetTokenTimeout requestTokenTimeout:(NSTimeInterval)requestTokenTimeout;

接口作用

分开设置预取号和取号请求超时时间

调用时机

  • 调用registerWithAppID前先设置请求超时时间

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 分别设置预取号和取号请求超时时长

    [OneLogin setRequestTimeout:10 requestTokenTimeout:10];
    [OneLogin registerWithAppID:@"您的appID"];

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 分别设置预取号和取号请求超时时长

    // 进入授权页面
    OneLogin.setRequestTimeout(10, requestTokenTimeout: 10)
    OneLogin.register(withAppID: "您的appID")

8、更改隐私条款勾选框状态

方法原型

/**
/**
@abstract 设置服务条款左边复选框勾选状态
@param isChecked 是否勾选
*/
+ (void)setProtocolCheckState:(BOOL)isChecked;

接口作用

更改隐私条款勾选框状态

调用时机

  • 可使用hintBlock自定义未勾选隐私条款勾选框点击授权按钮的操作,然后调用此接口勾选条款

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 更改隐私条款勾选框状态

    [OneLogin setProtocolCheckState:YES];

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 更改隐私条款勾选框状态

    OneLogin.setProtocolCheckState(true)

9、开始取号

方法原型

/**
* @abstract 开始取号
*/
+ (void)startRequestToken;

接口作用

开始取号

调用时机

  • 使用customAuthActionBlock返回YES自定义授权页面登录按钮点击事件,点击授权按钮后先接入其他验证方式,在此加入接入方的逻辑,验证通过后调用startRequestToken方法继续执行取号操作

示例代码

ObjC:

  1. 导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 开始取号

    [OneLogin startRequestToken];

Swift:

  1. 创建混编桥接头文件并导入极验 SDK 头文件 #import <OneLoginSDK/OneLoginSDK.h>

  2. 开始取号

    OneLogin.startRequestToken()