一键认证

一键认证

1.能力简述

一键认证:一键认证方案,运营商利用其移动数据网络,采用“通信网关取号”及 SIM卡识别等技术,准确验证用户本机号码,实现一键认证,并可有效规避短信验证码泄露风险。 通过运营商网关认证能力,用户无需输入手机号码和短信验证码,即可使用手机号一键认证成功。

使用限制说明:一键认证功能的使用前提是用户打开蜂窝网络,目前支持的网络制式有移动 2G、3G、4G,联通 3G、4G,电信 4G。对于双卡手机支,以开启数据流量的 SIM 卡进行认证;对于Wifi环境,在数据网络开通的前提下,会强制使用数据网络触发网关请求,请求仅为几K,可正常校验。 另外,一键认证当前不支持分屏显示,建议此功能不要应用在分屏显示场景下。

2.接入前准备

(1)请联系QQ:3007288195 开通权限。

(2)调用接口前请先完成个验SDK的接入与初始化。

3.业务流程

业务流程图:

注意

"绿色流程”由接入方实现对接。

“蓝色流程”由个推实现,接入方可进行了解。

成功对接效果图:

4.添加应用Logo

接入方可以根据自己产品需要接入自己产品的Logo,如果不接入自己产品的Logo,将使用默认的Logo。
接入方添加自己应用的Logo的步骤如下:

  1. TYRZResource.bundle 引入到项目
  2. TYRZResource.bundle/logo.png 替换为自已应用的图标

注意事项: Logo图标名称必须命名为logo_80x80_.png 或自行设置 appLogo 属性。

5.配置ATS

目前运营商个别接口为http请求,对于全局禁用http的项目,需要设置http白名单。以下为运营商http接口域名和ip名单:cmpassport.com、id6.me、mdn.open.wo.cn。配置ATS,在 info.plist 文件中添加 App Transport Security Settings 项,并在其中添加 Exception Domains 子项,设置如下:

6.接口说明

6.1 接口列表

方法 功能说明
setEloginTimeout 设置一键认证和号码校验预登录阶段的超时时间
preGetToken 【一键认证】预登录获取token等信息
oneTapLogin 【一键认证】一键认证接口

6.2 设置超时

/**
 * 设置一键认证和号码校验预登录阶段的超时时间
 * @param timeout 单位秒
 */
+ (void)setEloginTimeout:(NSTimeInterval)timeout;

6.3 一键认证

6.3.1 预登陆获取token

/**
 * 预登陆,若成功,则可以调用一键认证接口,打开登录页面
 * @param callback 结果回调
 */
+ (void)preGetToken:(GyVerifyCallback)callback;

注意:预登录操作用于提前判定当前网络环境是否适合使用一键登录,建议在登录操作前调用,不影响登录流程,降低对用户体验的影响。例如:初次打开APP、进入个人中心页(“我的”),等。预登录结果的有效期是10分钟,且只能使用一次。也就是第二次调用一键认证接口时,需要再次先调用预登录。
预登录成功表示当前设备可以使用一键认证,失败则表示不可用,开发者在失败的时候可以换成其他登录方式。

6.3.1.1 输入参数
参数名称 是否必填 类型 描述
callBack GyVerifyCallback 结果回调
6.3.1.2 调用示例
[GeYanSdk preGetToken:^(NSDictionary *tokenDic) {
    NSLog(@"获取token返回结果:%@", tokenDic);
}];
6.3.1.3 返回示例

校验token会通过 GyVerifyCallback 返回结果.

GyVerifyCallback:

typedef void (^GyVerifyCallback)(NSDictionary *verifyDictionary);

verifyDictionary返回示例和说明:

{
    code = 30000; // NSNumber, 非30000为失败的状态码
    processID = 47dab9b7c26629cd9bc117f88e2f9233; // NSString, 流水号
    operatorType = 4; // NSString, 操作类型
    accessCode = "xxxxx"; // NSString, 预登录返回的token
  errorCode = "-30003", // NSString, 运营商返回的错误码
    msg = "\U83b7\U53d6accessCode\U6210\U529f"; // NSString, 运营商返回的描述消息
    metadata = {}; // NSDictionary, 失败时, 运营商的响应内容。
}

注意: 因运营商差异,移动运营商不会返回token,电信和联通会返回token。

6.3.2一键认证接口

/**
 * 一键认证
 * @param controller 当前viewController
 * @param model GYAuthViewModel 自定义view参数
 * @param callback 通用接口回调
 */
+ (void)oneTapLogin:(UIViewController *)controller withViewModel:(GyAuthViewModel *)model andCallback:(GyVerifyCallback)callback;

6.3.2.1 输入参数
参数名称 是否必填 类型 描述
clickHandler GyClickHandler 自定义事件点击回调
callBack GyVerifyCallback 一键登陆结果回调
6.3.2.2 调用示例
//调用此接口接口前请调用 preGetToken 并成功获取到 accessCode
GyAuthViewModel *authViewModel = [[GyAuthViewModel alloc] init];
GyAuthPrivacyItem *item1 = [[GyAuthPrivacyItem alloc] initWithTitle:@"隐私条款一"
                                                            linkURL:[NSURL URLWithString:@"https://getui.com"]];
GyAuthPrivacyItem *item2 = [[GyAuthPrivacyItem alloc] initWithTitle:@"隐私条款二"
                                                            linkURL:[NSURL URLWithString:@"https://getui.com"]];
authViewModel.additionalPrivacyTerms = [@[item1, item2] mutableCopy];
[GeYanSdk oneTapLogin:self withViewModel:authViewModel andCallback:^(NSDictionary *verifyDictionary) {
    NSLog(@"一键认证返回结果:%@", verifyDictionary);
    [GeYanSdk closeAuthVC];
}];
6.3.2.3 返回示例

一键认证会通过 GyVerifyCallback 返回结果.

GyVerifyCallback:

typedef void (^GyVerifyCallback)(NSDictionary *verifyDictionary);

一键认证verifyDictionary返回示例和说明:

{
    code = 30000; // NSNumber, 非30000为失败的状态码
    processID = 47dab9b7c26629cd9bc117f88e2f9233; // NSString, 流水号
    operatorType = 4; // NSString, 操作类型
    errorCode = "-30003", // NSString, 失败时,运营商返回的错误码
    msg = "\U83b7\U53d6accessCode\U6210\U529f"; // NSString, 描述消息
    metadata = {}; // NSDictionary, 失败时, 运营商的响应内容。
    token = "xxx",  //NSString, 登陆成功返回的用户授权凭证信息,可以用于在服务端获取登录信息
    expiredTime: 155555555555, //NSInteger,成功时, token失效时间戳
    pn: "133****3333", //NSString,成功时, 脱敏7位手机号码
}

6.3.3 本地资源包安全校验

TYRZResource.bundle必须添加到工程,否则可能会引起crash
若对自定义界面有需求,请参考GYAuthViewModel介绍进行开发,若无自定义界面需求,替换TYRZResource.bundle中的图片资源文件即可

7.状态码

7.1 code

错误码 含义
30000 登录成功
30001 当前环境不适合免密登录
30002 用户点击了其他登录方式
30003 用户关闭验证界面
30004 其他错误,具体见返回
30005 预登陆错误
30006 一键认证错误
40047 一键认证取号失败

8.一键认证错误码对照表

8.1 errorCode

错误码 含义
-20101 未配置 AppID, 请先配置 AppID
-20102 重复调用预登录接口
-20102 重复调用取号接口
-20202 当前没有开启蜂窝网络, 请检查是否开启蜂窝网络。
-20203 不支持的运营商。OneLogin 仅支持在大陆地区支持三大运营商。
-20204 无效的 accessCode 。确保每次调用 OneTapLogin 之前,都成功调用 preGetToken
-20302 用户点击返回键并退出取号页面。授权页面会自动关闭。
-20303 用户点击了切换账号按钮。授权页面不会自动关闭。
-40101 移动运营商预登录失败。请检查数据网络可用性。
-40102 移动运营商取号失败。请检查数据网络可用性。
-40198 移动运营商预登录异常。请检查数据网络可用性。
-40199 移动运营商取号异常。请检查数据网络可用性。
-40201 联通运营商预登录失败。请检查数据网络可用性。
-40204 联通运营商取号失败。请检查数据网络可用性。
-40298 联通运营商预登录异常。请检查数据网络可用性。
-40299 联通运营商取号异常。请检查数据网络可用性。
-40301 电信运营商预登录失败。请检查数据网络可用性。
-40302 电信运营商取号失败。请检查数据网络可用性。
-40398 电信运营商预登录异常。请检查数据网络可用性。
-40399 电信运营商取号异常。请检查数据网络可用性。
-50100 一键登录服务接口返回异常
-50101 一键登录服务返回业务失败
-50102 一键登录服务接口网络异常。请检查网络可用性。

8.2 运营商错误码

运营商接口返回失败常见的错误代码,位于错误回调JSON中meta_data内的运营商错误码

8.2.1 移动运营商

错误码 含义
102102 网络异常
102507 登录超时(授权页点登录按钮时)
103101 appkey错误
103102 包签名错误
103108 短信验证码错误
103109 短信验证码校验超时
103111 网关IP错误(运营商误判)
103119 appid不存在
103125 号码格式错误
103203 缓存失效
103211 其他错误
103901 短验下发次数已达上限(5次/min,10次/day)
103902 scrip失效
103911 token请求过于频繁,10分钟内获取token且未使用的数量不超过30个
105001 联通取号失败
105002 移动取号失败
105003 电信取号失败
105021 已达当天取号限额
105302 appid不在白名单
200005 用户未授权(READ_PHONE_STATE)
200010 取号请求时获取imsi失败
200014 号码不存在
200020 用户取消登录
200021 数据解析异常
200022 无网络
200023 请求超时
200024 数据网络切换失败
200025 其他错误(socket、系统未授权数据蜂窝权限等)
200026 输入参数错误
200027 未开启数据网络
200028 网络请求出错
200030 没有初始化参数
200038 电信重定向失败
200039 电信取号接口返回失败
200040 UI资源加载异常
200048 未安装sim卡
200050 EOF异常
200060 切换账号(未使用SDK短验时返回)
200061 授权页面异常
200062 预登录不支持联通
200063 预登录不支持电信

8.2.2 电信运营商

错误码 含义
-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失效,请查看5.3常见问题。
51002 参数为空
51114 取号失败
-8001 请求网络异常
-8002 请求参数异常
-8003 请求超时
-8004 移动网络未开启
-8005 请先初始化SDK
-8100 网络无连接
-8101 响应码错误
-8102 Socket超时异常(读取超时、连接超时)
-8103 域名解析异常
-8104 IO异常
-8201 响应码错误
-720001 切换异常
-720002 切换异常超时

8.2.3 联通运营商

错误码 含义
100 应用未授权
101 应用秘钥错误
102 应用无效
103 应用未授权该IP访问
104 应用访问次数不足
105 应用包名不正确
200 tokenId无效
201 token已失效
202 token未授权该应用访问
203 登录鉴权级别不满足接口鉴权要求
300 接口未开放
301 应用未授权码访问该接口
302 IP未授权码访问该接口
303 应用访问接口次数超日限额
400 请求参数为空
401 请求参数不完整
402 请求参数非法
600 请求非法
1000 请求解析错误
1001 请求已失效
1002 验签失败
1003 授权码已过期
1004 加密方式不支持
1005 RSA加密错误
1010 服务间访问失败
1011 服务间访问错误
2004 用户不存在
3001 unikey无效
3002 跳转异网取号
3003 本网执行取号失败,不需要重定向
3004 NET取号失败
3005 上网方式为WIFI,无法取号
3006 urlencode编码失败
3007 请求认证接口异常
3008 imsi取号失败
3009 非联通号码
3010 网关取号错误
3011 源IP鉴权失败
3012 网关取号失败
3013 电信网关取号失败
3014 电信网关取号错误
3015 获取accessCode请求参数失败
3016 移动网关取号失败
3017 移动网关取号错误

常见问题

建议开发者在开发期间开启debug模式,通过查看debug日志,可以更好的排查问题。

[GeYanSdk setDebug:YES];

一键登录和本机号码校验支持哪些运营商和网络环境

目前支持移动 2G、3G、4G,联通 3G、4G,电信 4G。

是否支持双卡手机

支持,双卡手机以开启数据流量的 SIM 卡进行认证。

WIFI环境下能否验证

在数据网络开通的前提下,WiFi 环境中会强制使用数据网络触发网关请求,请求仅为几K,可正常校验。

是否支持携号转网用户

SDK 不提供接口判断用户是否为携号转网用户,但可以判断用户流量卡当前的运营商。即携号转网用户可正常使用。

是否支持虚拟运营商

仅支持三大运营商(移动、联通、电信)的手机号进行一键登录。

是否支持流量卡

三大运营商(移动、联通、电信)的卡,能够正常使用数据网络,运营商通过网关能够正常取号,均会被作为正常的卡来判断。

文档中心搜索