本文为您介绍号码认证服务本机号码校验(iOS)的配置流程。

1. 概述

官网下载SDK后进行解压,解压后包含三个文件是

  • iOS SDK开发接入文档
  • AliComSDKDemo工程
  • ATAuthSDK.framework

号码认证服务包含本机号码校验和一键登录两个不同的功能,使用场景不一样,无需一起使用。

本机号码校验使用场景:用户输入手机号码,通过SDK获取token(通过getVerifyTokenWithTimeout获得),服务端携带输入的手机号码和token去运营商网关进行校验(服务端调用VerifyMobile接口),返回的结果是用户当前上网使用的号码与输入的号码是否一致。

一键登录使用场景:用户无需输入手机号码,SDK会拉起授权页,用户确认授权后,SDK会获取token(通过getLoginTokenWithTimeout获得),服务端携带token到运营商网关获取用户当前上网使用的号码(服务端调用GetMobile接口),并返回给App服务端。

2. 准备工作

  • 请确保您的终端设备已经开启了4G网络(联通、移动支持3G网络,但接口耗时会增加)
  • 请确保已经在阿里云控制台开通了号码认证服务并创建了对应的方案,点击进入阿里云控制台。方案创建成功后,联通电信可立即使用,移动需等待10分钟后使用。
  • 您也可以登录阿里云官网查看接入流程,点击查看完整使用流程。

3. 运行demo工程

解压后包含AliComSDKDemo工程,您需要将【bundleID、秘钥和开发者证书】修改为您自己的。

4. 开发环境搭建

  • 添加主库

    Targets->General->Linked Frameworks and Libraries 中添加主库ATAuthSDK.framework;

    或者Xcode 11中Targets->General->Frameworks,Libraries, and Embedded Content 中添加主库ATAuthSDK.framework;

  • Targets->BuildSettings设置

    Targets->BuildSettings 中 , Other Linker Flags增加-ObjC,一定要添加此选项,注意是大写C,不是小写c,否则工程运行会crash!

  • 添加资源文件

    主项⽬右键添加下ATAuthSDK.framework中ATAuthSDK.bundle资源⽂件,否则⼀键登录授权⻚⾯默认的图⽚或icon显示不出来;

5. SDK 使用说明

5.1 SDK功能介绍

  • 阿里云号码认证iOS SDK目前主要提供功能,目前仅提供静态库ATAuthSDK.framwork形式。
  • 获取SDK版本号。
  • SDK接口调用环境检查及准备,检测设备是否开启蜂窝数据网络,且配置SDK相关数据,该步骤是本机号码校验及一键登录功能可以使用的前提条件。
  • 本机号码校验getVerifyTokenWithTimeout接口(支持移动,电信,联通三大运营商),请求本机号码校验的凭证,可自定义超时时间,默认3.0s,单位s。

    1) 调用接口setAuthSDKInfo,初始化SDK秘钥参数 **2) **调用接口checkEnvAvailableWithComplete,检查及准备SDK环境 **3) **调用SDK本机号码校验获取token接口getVerifyTokenWithTimeout获取本机号码校验token **4) **调用服务端VerifyMobile接口进行本机号码校验

5.3 本机号码校验接口调用说明

6. SDK方法说明

6.1 主类TXCommonHandler接口简介

6.1.1 获取认证实例(sharedInstance)

/**
	*函数名:sharedInstance
	*@param 无
	*返回:获取该类的单例实例对象
*/
+(instancetype _Nonnull )sharedInstance; 
			

6.1.2 获取sdk版本号(getVersion)

/** 
	* 函数名:getVersion
	* @param 无
	* 返回:字符串,sdk版本号
*/
-(NSString *_Nonnull)getVersion;
			

6.1.3 设置SDK秘钥(setAuthSDKInfo)

/**
	* 函数名:setAuthSDKInfo
	* @brief 初始化SDK调用参数,app生命周期内调用一次
	* @param  方案对应的秘钥,请登录阿里云控制台后,进入认证方案管理,点击秘钥后复制秘钥,建议维护在业务服务端
	* @param complete 结果同步回调,成功时resultDic=@{resultCode:600000, msg:...},其他情况时"resultCode"值请参考PNSReturnCode
*/
- (void)setAuthSDKInfo:(NSString * _Nonnull)info complete:(void(^_Nullable)(NSDictionary * _Nonnull resultDic))complete;
			

6.1.4 检查认证环境(checkEnvAvailableWithComplete)

/**
	* 函数名:checkEnvAvailableWithComplete
 	* @brief	检查及准备调用环境,resultDic返回PNSCodeSuccess才能调用下面的功能接口,在初次或切换蜂窝网络之后需要重新调用,一般在一次登录认证流程开始前调一次即可
	* @param	complete 异步结果回调,成功时resultDic=@{resultCode:600000, msg:...},其他情况时"resultCode"值请参考PNSReturnCode,只有成功回调才能保障后续接口调用
*/
- (void)checkEnvAvailableWithComplete:(void (^_Nullable)(NSDictionary * _Nullable resultDic))complete;
			

6.1.5 本机号码校验获取token(getVerifyTokenWithTimeout)

/**
	* 函数名:getVerifyTokenWithTimeout
	* @param timeout:接口超时时间,单位s,默认3.0s,值为0.0时采用默认超时时间
	* @param complete 结果异步回调,成功时resultDic=@{resultCode:600000, token:..., msg:...},其他情时"resultCode"值请参考PNSReturnCode
*/
 - (void)getVerifyTokenWithTimeout:(NSTimeInterval)timeout complete:(void (^_Nullable)(NSDictionary * _Nonnull resultDic))complete;
			

6.2 工具类TXCommonUtils接口简介

6.2.1 判断设备蜂窝网络是否开启(checkDeviceCellularDataEnable)

/**
 	* 函数名:checkDeviceCellularDataEnable
*/
+ (BOOL)checkDeviceCellularDataEnable;
			

6.2.2 判断当前上网卡是否是中国联通(isChinaUnicom)

/**
 	* 函数名:isChinaUnicom
*/
+ (BOOL)isChinaUnicom;
			

6.2.3 判断当前上网卡是否是中国移动(isChinaMobile)

/**
 	* 函数名:isChinaMobile
*/
+ (BOOL)isChinaMobile;
			

6.2.4 判断当前上网卡是否是中国电信(isChinaTelecom)

/**
 	* 函数名:isChinaTelecom
*/
+ (BOOL)isChinaTelecom;
			

6.2.5 获取当前上网卡网络名称(getCurrentMobileNetworkName)

/**
 	* 函数名:getCurrentMobileNetworkName
 	* @return ChinaMobile,ChinaUnicom,ChinaTelecom,OtherChinaMobileNetwork,NoChinaMobileNetwork
*/
+ (NSString *)getCurrentMobileNetworkName;
			

6.2.6 获取当前上网卡运营商名称(getCurrentCarrierName)

/**
 	* 函数名:getCurrentCarrierName
 	* @return:中国移动,中国联通,中国电信等
*/
+ (NSString *)getCurrentCarrierName;
			

6.2.7 获取当前上网网络类型(getNetworktype)

/**
 	* 函数名:getNetworktype
 	* @return:WiFi,4G,3G,2G,NoInternet等
*/
+ (NSString *)getNetworktype;
			

6.2.8 判断设备是否有SIM卡(simSupportedIsOK)

/**
 	* 函数名:simSupportedIsOK
 	* @return:
*/
+ (BOOL)simSupportedIsOK;
			

6.2.9 判断wwan是否开启(isWWANOpen)

/**
 	* 函数名:isWWANOpen
 	* @breif:判断wwan是否开启(通过p0网卡判断,无wifi或有wifi情况下都能检测到)
*/
+ (BOOL)isWWANOpen;
			

6.2.10 判断无wifi下wwan是否开启(reachableViaWWAN)

/**
 * 函数名:reachableViaWWAN
 * @return:
 */
+ (BOOL)reachableViaWWAN;
			

6.2.11 获取设备当前网络私网IP地址(getMobilePrivateIPAddress)

/**
	* 函数名:getMobilePrivateIPAddress
	* @return:
*/
+ (NSString *)getMobilePrivateIPAddress;
			

6.3 一键登录获取手机号

当您成功获取到getLoginTokenWithTimeout成功获取token后,将token传递至您的服务端,服务端携带token调用阿里云的getMobile接口即可进行最终的取号操作。

6.4 SDK返回码

该返回码为阿里云号码认证SDK⾃身的返回码,请注意600011及600012错误内均含有运营商返回码,具体错误在碰到之后查阅运营商SDK返回码

返回码 返回码描述 建议
600000 获取token成功
600004 获取运营商配置信息失败 创建工单联系工程师
600007 未检测到sim卡 提示用户检查 SIM 卡后重试
600008 蜂窝网络未开启 提示用户开启移动网络后重试
600009 无法判断运营商 创建工单联系工程师
600010 未知异常 创建工单联系工程师
600011 获取token失败 切换到其他登录方式
600012 预取号失败 切换到其他登录方式
600013 运营商维护升级,该功能不可用 创建工单联系工程师
600014 运营商维护升级,该功能已达最大调用次数 创建工单联系工程师
600015 接口超时 切换到其他登录方式
600017 AppID、Appkey解析失败 创建工单联系工程师
600021 点击登录时检测到运营商已切换 切换到其他登录方式

7. SDK接入demo用例

7.1 本机号码校验调用demo

NSString *info = @"客户的秘钥串";
    __weak typeof(self) weakSelf = self;
    //设置SDK参数,app生命周期内调用一次即可
    [[TXCommonHandler sharedInstance] setAuthSDKInfo:info complete:^(NSDictionary * _Nonnull resultDic) {
        [weakSelf showResult:resultDic];
    }];


if (self.tf_phoneNumber.text.length == 0) {
        [ProgressHUD showError:@"请先输入手机号码"];
        return;
    }
    
    float timeout = self.tf_timeout.text.floatValue;
    [ProgressHUD show:@"请稍等..." Interaction:YES];
    __weak typeof(self) weakSelf = self;
    
    //1. 调用check接口检查及准备接口调用环境
    [[TXCommonHandler sharedInstance] checkEnvAvailableWithComplete:^(NSDictionary * _Nullable resultDic) {
        if ([PNSCodeSuccess isEqualToString:[resultDic objectForKey:@"resultCode"]] == NO) {
            [ProgressHUD showError:@"check 接口检查失败,环境不满足"];
            [weakSelf showResult:resultDic];
            return;
        }
        //2. 获取 VerifyToken
        [[TXCommonHandler sharedInstance] getVerifyTokenWithTimeout:timeout complete:^(NSDictionary * _Nonnull resultDic) {
            if ([PNSCodeSuccess isEqualToString:[resultDic objectForKey:@"resultCode"]] == NO) {
                [ProgressHUD showError:@"获取 VerifyToken失败"];
                [weakSelf showResult:resultDic];
                return ;
            }
            //3. 去服务器验证 VerifyToken
            [weakSelf showResult:resultDic];
            NSString *token = [resultDic objectForKey:@"token"];
            //注: 这里请求是通过自己服务器, 下面仅供参考
            [PNSVerifyTopRequest requstVerifyWithNumber:weakSelf.tf_phoneNumber.text token:token complete:^(BOOL isSuccess, NSString * _Nonnull msg, NSDictionary * _Nonnull data) {
                NSDictionary *module = data[@"module"];
                NSString *verify_result = [module objectForKey:@"verify_result"];
                if ([verify_result isEqualToString:@"PASS"]) {
                    [ProgressHUD showSuccess:@"本机号码校验成功"];
                } else {
                    [ProgressHUD showSuccess:@"本机号码校验失败"];
                }
                [weakSelf showResult:data];
            }];
        }];
    }];
			

8. iOS常见问题

  1. 初始化接口checkEnvAvailableWithComplete一直返回NO? 排查顺序:1、手机sim卡是否被激活或欠费;2、手机设备蜂窝数据是否开启;3、App的网络权限是否开启;4、设备是否有代理;5、云控制台上是否创建了方案号;6、创建方案号中的bundleId一定要与项目中使用的保持一致;7,设备时间设置是否非标准,不能修改手机时间戳提前或延期;8,是否调用了setAuthSDKInfo接口;9,最后再提供bundleId给我们进行查询日志;

  2. 移动卡出现crash【[UAReachability reachableType]: unrecognized selector sent to instance】 在主工程中Project -> Edit Active Target -> Build Setting -> Other Linker Flags中添加-all_load标记,前提也要添加-ObjC,即两者都要添加;

  3. 登录token存在失败吗? 肯定存在的,如果是偶现,可以理解,因为比如网络波动导致网关断开、网络不可用、供应商服务端异常,业务方服务端异常等因素有关;如果是持续出现,一般需要运营商协助排查;

  4. 一键登录服务一般只4G或者4G+Wifi情况下,如果是3G、2G会怎么样? 中国移动支持2G/3G/4G、中国联通支持3G/4G、中国电信支持4G,但2G和3G网络下接口请求失败或超时概率稍高。

  5. 经常超时? 首先确认sim卡不欠费,再确认手机网络是否正常,通过Safari打开某个网址验证为准。其次确认超时时间是否设置正确,单位是s。 2G和3G网络下接口请求失败或超时概率稍高。 切换网络时,设置网络不稳定,会较大概率出现超时。