华为云手机号码认证移动端SDK接入集成指引

SDK集成(华为客户端)
 
1、  初始化
 
SDK初始化后才可以正常调用,因此初始化方法也可以视为SDK的总开关,若想关停SDK,不调用初始化即可。
 
2、  取号方法
 
通过调用安卓的getPhoneInfo或iOS的getPhoneNumberCompletion,在用户无感知的情况下进行网络判断、蜂窝数据网络切换和网关取号等操作(以上操作均需消耗一定时间),返回取号是否成功的结果。
 
(1)取号所需网络环境
 
运营商取号能力是通过数据网关实现,取号过程须在数据流量打开的情况下才能进行。因此,用户如果关闭数据流量将无法取号;若当前信号弱或者网络有干扰时,时延会高于平均值,取号成功率降低。
 
(2)超时设置
 
SDK默认超时设置为8000ms,同时提供设置取号超的方法:安卓通过setOverTime设置,iOS通过setTimeoutInterval设置。
 
(3) 运营商判断
 
SDK提供判断用户当前网络状态和流量卡所属运营商的方法,通过调用安卓SDK的getNetworkType或iOS的networkInfo可获得以上信息,以便对不同用户选择不同的运营商的SDK进行取号或选择不同的登录方式。
 
(4) 关于取号缓存
 
应用取号或者授权成功后,SDK将取号的一个临时凭证缓存在本地,缓存能有效提高取号成功率、降低时延,并允许用户在未开启蜂窝网络时成功取号。SDK本身对缓存有处理逻辑,在某些场景下(如换卡)会让缓存提前失效,但若应用对安全性要求较高,也可以通过SDK提供的方法(安卓的delScrip和iOS的delectScrip)让缓存马上失效。
 
注:清除缓存的方法可在任何时候调用,但不建议在即将拉起授权页时调用,以免造成SDK在拉起授权页前还需要重新取号导致时延增加,影响用户体验。
 
3、  授权方法
 
通过调用安卓的loginAuth或iOS的getAuthorizationWithModel,SDK将拉起用户授权页面,用户确认授权后,SDK将返回token给应用客户端。
 
(1)授权页的拉起
 
当取号缓存scrip(可通过取号方法生成)有效时,SDK能几乎无耗时地拉起授权页(业务可通过返回码200087监听授权页是否成功拉起);当取号缓存scrip已失效(用户换卡、缓存有效期已过等)或不存在时,SDK需要先消耗一定时间进行取号,取号成功才能拉起授权页。此取号阶段的用户交互(如取号缓冲页)由业务方自行处理。
 
(2)授权页元素的半自定义和插入自定义控件
 
对页面内的元素的自定义,请参考SDK接入文档的【授权页面设计】章节,或参考demo文件;若希望在页面中插入其他第三方登录方式,或其他内容,安卓可以通过【授权页布局】实现,iOS可以通过【自定义控件】实现
 
注:自定义的控件不允许覆盖SDK默认的UI。
 
(3)授权页的关闭
 
为提供更灵活的授权页处理方式,SDK将大部分的授权页关闭逻辑交给业务方处理,可分为以下两种模式:
 
模式1:授权页面的自动关闭在授权登录页面,当用户主动点击取消登录时,授权页面会自动关闭;安卓SDK,当用户点击手机的返回键(相当于取消登录),授权页面会自动关闭。
 
模式2:开发者自定义关闭除模式1的场景外,其余所有授权页关闭需要由开发者自行实现,请参考SDK说明文档;建议在调用关闭授权页的方法前对当前页面进行监控,以免关闭了非SDK的页面。
 
注:对于安卓5.7.1的SDK,当前在关闭授权页时会回调200020(授权页关闭)的返回码。
 
(4)token获取的限制
 
token有效期2min,一次有效;同一用户(手机号)10分钟内获取token且未使用的数量不超过30个。
 
(5)授权页行为捕捉和统计分析
 
授权页的拉起:监听返回码200087(授权页成功拉起),该返回码的处理方式可参考demo。
 
授权页授权按钮的行为捕捉:iOS可以通过返回码监控,如102507(登录超时)、200020(用户取消登录);安卓可以通过setLogBtnClickListener进行监听(触发回调就说明点击了登陆按钮)。
 
开发者自定义控件:由开发者自行捕捉。
 
4、  本机号码校验
 
通过调用安卓的mobileAuth或iOS的mobileAuthCompletion方法,可在不拉起授权页的情况下获得token。此时获得的token不能用于兑换用户的完整号码,只能用于校验本机号码与待校验号码的一致性。
 
(1)预取号
 
安卓的getPhoneInfo或iOS的getPhoneNumberCompletion所形成取号缓存scrip同样适用于本机号码校验,可提前进行取号以提高后续获取token的效率。
 
(2)适用场景
 
可在用户无感知的情况下校验本机号码与待校验号码的一致性,适用于所有基于手机号码进行风控的场景。
 
服务端联调
 
服务端用于凭token兑换用户授权的本机号码,或进行本机号码校验(是两个不同的接口)。以上两个接口均需报备服务端出口IP地址后才能正常使用,不允许从客户端直接调用。
 
1、一键登录
 
一键登录token校验接口支持MD5验签和RSA验签两种模式。
 
(1)MD5验签
 
1) 验签方式选择APPSecret。
 
2) 根据验签方式,拼接参数后生成sign
 
3) 按文档要求补充其他参数后请求loginTokenValidate接口
 
4) 响应参数中的msisdn即为11位的用户号码
 
(2)RSA验签(请开发者选择RSA延签)
 
1) 使用PKCS#8生成公私钥,并将公钥在base64编码后报备到华为认证后台
 
2) 请求报文中的encryptionalgorithm填写“RSA”
 
3) 通过私钥进行签名(appid+token,“+”号为合并意思,不包含在被加密的字符串中),签名算法为SHA256withRSA,并进行hex编码
 
4) 按文档要求补充其他参数后请求loginTokenValidate接口
 
5) 使用私钥解密响应参数中的msisdn即可获得手机号码
 
2、本机号码校验
 
本机号码校验的token校验接口支持HMACSHA256验签和RSA验签两种模式
 
(1)HMACSHA256验签和SHA256加密
 
1) keyType写0或不填
 
2) 生成phoneNum字段:拼接【手机号码+appKey+timestamp】,再使用sha256进行加密(“+”号为合并意思,不包括在要加密的内容中)
 
3) 生成sign字段:以appkey为秘钥,HMACSHA256(appId+msgId+phonNum+timestamp+
 
token+version),输出64位大写字母(注:“+”号为合并意思,不包含在被加密的字符串中;phonNum为加密后的,跟报文中的“phoneNum”一致)
 
4) 按文档要求补充其他参数后请求
 
5) 获得是否本机号码的校验结果
 
(2)RSA验签
 
1) 使用PKCS#8生成1024位的公私钥,并将公钥在base64编码后报备到华为认证后台后,获得平台公钥
 
2) keyType写1
 
3) 使用平台公钥生成phoneNum字段:拼接【手机号码+appKey+timestamp】(“+”号为合并意思,不包括在要加密的内容中),再使用华为认证提供的平台公钥加密,加密算法为MD5withRSA
 
4) 使用应用私钥生成sign字段:使用在华为认证后台报备RSA公钥所对应的私钥进行加密,加密内容为【appId+msgId+phonNum+timestamp+token+version】(“+”号为合并意思,不包括在要加密的内容中;phonNum为加密后的,跟报文中的“phoneNum”一致),加密算法为MD5withRSA
 
5) 按文档要求补充其他参数后请求
 
6) 获得是否本机号码的校验结果
 
3、服务端联调常见问题

返回码

排查方式

103101

签名错误,先确认签名生成方式是RSA还是MD5,以及验签方式是APPKEY还是APPsecret

如果是MD5,如果是APPKEY,就用APPKEY拼接生成sign,如果是APPSecret,就用APPSecrett生成sign

如果是RSA,请检查公钥是否正确报备并使用,再检查使用的算法。

103113

token内容错误,请确认token是否为SDK签发的token

103119

不存在这个appid,开发者自行检查appid的填写是否有误

103133

指客户端获取token和服务端token校验使用的APPID不一致,请联系应用客户端研发共同确认获取token使用的appid

103211

其他错误,常见于报文格式不对,先请检查是否符合这三个要求:

1json形式的报文交互必须是标准的json格式;

2)发送时请设置contenttypeapplication/json

3)参数类型都是String

若使用了RSA加解密的方式,请登录dev.10086.cn的移动认证能力管理后台检查公钥

填写是否有误,确认无误后重新提交并重试。