本文介绍了获取无线认证SDK后,将认证SDK集成到您的iOS应用中的操作方法。

注意 实人认证产品iOS SDK已完成WKWebview改造,您可以在实人认证控制台自助下载SDK进行升级,升级时请按照本文档重新集成。

前提条件

已获取正确的iOS SDK,目前不支持bitcode。

权限配置

实人认证依赖了相机&相册权限,需要你在xcode工程的info.plist文件里面配置相机权限,配置如下:
<!-- 相机 -->
<key>NSCameraUsageDescription</key>
<string>App需要您的同意,才能访问相机</string> // 文案描述可自定义。

<!-- 相册 -->
<key>NSPhotoLibraryUsageDescription</key>
<string>App需要您的同意,才能访问相册</string>  // 文案描述可自定义。

iOS应用集成SDK

方式一:Pod库集成iOS

注意 如果之前您采用的不是Pod库集成iOS的方式,则需要您把之前的依赖库和资源全部删除,然后再通过Pod库集成iOS。
  1. 在Podfile中指定source。
    1. 添加阿里云Pod仓库。
      pod repo add aliyun-specs https://github.com/aliyun/aliyun-specs.git
    2. 在podfile头部指定source。
      # 请不要遗漏Master仓库。
      source 'https://github.com/CocoaPods/Specs.git'
      source 'https://github.com/aliyun/aliyun-specs.git'
  2. 在您的工程中添加以下实人认证需要的系统依赖库。
      pod 'AlicloudRPSDK', '4.13.3'
      pod 'AliyunOSSiOS', '2.10.8'
      pod 'AlicloudSGSecurityBody', '5.5.74'
  3. 导入在实人认证控制台上下载的图片yw_1222_0769.jpg。导入时必须勾选Copy items if needed
    在控制台上下载ZIP包并解压,在解压的文件中找到RPSDK.bundle文件,鼠标右键单击该文件,然后单击显示包内容,将图片yw_1222_0769.jpg导入到xcode工程。导入

方式二:在工程中导入SDK

  1. 在您的项目工程中导入实人认证依赖包。
    解压实人认证SDK后,将以下依赖包导入到您的项目工程中,导入时必须勾选Copy items if needed
    AliyunOSSiOS.framework
    RPSDK.framework
    SecurityGuardSDK.framework
    SGMain.framework
    SGSecurityBody.framework
    说明 集成实人认证SDK后,应用大小的增量为2.89 MB。
  2. 在您的工程中添加以下实人认证需要的系统依赖库。
    CoreMotion.framework
    CoreTelephony.framework
    Libc++.tbd
    Libresolv.tbd
    Libz.tbd
    SystemConfiguration.framework
    导入的依赖包
    完成以上两个步骤后,您可以在Build Phases > Link Binary With Libraries看到导入的依赖包。如果未看到依赖包,说明导入过程中出现问题,请确认将所有依赖包拷贝到工程项目,并勾选正确的应用目标。
  3. 导入以下资源文件。导入时必须勾选Copy items if needed,表示自动复制一份相同的文件到工程中,并引用复制后的文件在工程目录中的位置。
    RPSDK.bundle
    111
    导入完成后,您可以在Build Phases > Copy Bundle Resources看到资源文件。如果未看到资源文件,则说明导入过程中出现问题,请确认将所有资源文件拷贝到工程项目,并勾选正确应用目标。
  4. 修改编译选项。在工程的Build Settings > Other Linker Flags选项中添加-ObjCObjC

使用SDK

在启用实人认证SDK前,需要您使用以下方法初始化实人认证SDK。

[RPSDK setup];
说明 调用实人认证客户端前,您必须先通过服务端调用DescribeVerifyToken获取verifyToken

方式一:start

默认推荐使用此方式调用实人认证,支持RPBasicRPBioOnlyRPBioIDRPManualFDBioOnlyFVBioOnly认证方案。该接口会以加载H5的方式显示页面,包含身份证件拍摄等其他步骤。

  • Objective-C
    // 由于安全原因,实人认证不支持模拟器调试。
    #import <RPSDK/RPSDK.h>
    
    [RPSDK startWithVerifyToken:verifyToken
                 viewController:self
                     completion:^(RPResult * _Nonnull result) {
        // 建议接入方调用实人认证服务端接口DescribeVerifyResult,来获取最终的认证状态,并以此为准进行业务上的判断和处理。
        NSLog(@"实人认证结果:%@", result);
        switch (result.state) {
            case RPStatePass:
                // 认证通过。
                break;
            case RPStateFail:
                // 认证不通过。
                break;
            case RPStateNotVerify:
                // 未认证。
                // 通常是用户主动退出或者姓名身份证号实名校验不匹配等原因导致。
                // 具体原因可通过result.errorCode来区分(详见文末错误码说明表格)。
                break;
        }           
    }];
    说明 errorCode说明请参见错误码说明
  • Swift
    // 由于安全原因,实人认证不支持模拟器调试。
    import RPSDK
    
    RPSDK.start(withVerifyToken: verifyToken, viewController: self) { result in
        // 建议接入方调用实人认证服务端接口DescribeVerifyResult,
        // 来获取最终的认证状态,并以此为准进行业务上的判断和处理。
        print("实人认证结果:", result);
        switch result.state {
        case .pass:
            // 认证通过。
            break
        case .fail:
            // 认证不通过。
            break
        case .notVerify:
            // 未认证。
            // 通常是用户主动退出或者姓名身份证号实名校验不匹配等原因导致。
            // 具体原因可通过result.errorCode来区分(详见文末错误码说明表格)。
            break
        default:
            break
        }
    }
    说明 errorCode说明请参见错误码说明
方式二:startByNative

如果您选择的认证方案只包含活体检测步骤,例如RPBioOnlyFDBioOnlyFVBioOnly,则可以考虑使用此方式接入。

  • Objective-C
    // 由于安全原因,实人认证不支持模拟器调试。
    #import <RPSDK/RPSDK.h>
    
    [RPSDK startByNativeWithVerifyToken:verifyToken
                         viewController:self
                             completion:^(RPResult * _Nonnull result) {
        // 建议接入方调用实人认证服务端接口DescribeVerifyResult,来获取最终的认证状态,并以此为准进行业务上的判断和处理。
        NSLog(@"实人认证结果:%@", result);
        switch (result.state) {
            case RPStatePass:
                // 认证通过。
                break;
            case RPStateFail:
                // 认证不通过。
                break;
            case RPStateNotVerify:
                // 未认证。
                // 通常是用户主动退出或者姓名身份证号实名校验不匹配等原因导致。
                // 具体原因可通过result.errorCode来区分(详见文末错误码说明表格)。
                break;
        }
    }];
    说明 errorCode说明请参见错误码说明
  • Swift
    // 由于安全原因,实人认证不支持模拟器调试。
    import RPSDK
    
    RPSDK.startByNative(withVerifyToken: verifyToken, viewController: self) { result in
        // 建议接入方调用实人认证服务端接口DescribeVerifyResult,来获取最终的认证状态,并以此为准进行业务上的判断和处理。
        print("实人认证结果:", result);
        switch result.state {
        case .pass:
            // 认证通过。
            break
        case .fail:
            // 认证不通过。
            break
        case .notVerify:
            // 未认证。
            // 通常是用户主动退出或者姓名身份证号实名校验不匹配等原因导致。
            // 具体原因可通过result.errorCode来区分(详见文末错误码说明表格)。
            break
        default:
            break
        }
    }
    说明 errorCode说明请参见错误码说明

可选配置

实人认证提供了一系列可选的配置,您可以通过以下方式来改变SDK的界面和行为。如果您使用默认配置,则无需关注以下内容。

配置选项接口在RPConfiguration.h文件中。在调用实人认证之前,您必须先创建实人认证配置实例,示例代码如下:
RPConfiguration *configuration = [RPConfiguration configuration];
  • UI定制

    实人认证服务为您提供UI定制功能,您可以根据实际需要自定义实人认证页面的按钮颜色、文案颜色、文案字体大小和图片资源等信息。UI定制功能仅适用于实人认证iOS SDK版本在4.6.2版本及以上。更多内容,请参见UI定制

    旧版UI设置方式已经废弃,请您及时更换设置方式,具体方法如下:

    // 设置皮肤路径即可(沙盒、bundle等都可以),不设置则使用默认皮肤。
    configuration.customUIPath = @"xxx/xxx/xxx";
  • 提示声音默认开关
    在活体检测过程中,默认开启提示声音,例如“眨下眼”、“左右摇头”等。如果您需要默认关闭提示音,可以在调用实人认证接口之前,使用以下方法进行定制。
    RPSDK.configuration.isMutedByDefault = YES;
    // YES表示默认关闭提示声音,NO表示默认开启提示声音。
  • 自定义扫脸页面弹出和关闭方式
    如果您需要自定义扫脸页面的弹出和关闭方式,可以在调用实人认证接口之前,使用以下方法进行定制。
    configuration.presentHandler = ^(UIViewController * _Nonnull viewController) {
        // 弹出扫脸页面。
    };
    configuration.dismissHandler = ^(UIViewController * _Nonnull viewController) {
        // 关闭扫脸页面。
    };
  • 活体检测结果页
    当用户完成活体检测时,默认会直接关闭活体检测页面。如果您需要用户在活体检测页面等待服务端返回认证结果,并显示加载中页面和结果页(结果页会在展示一秒后自动消失),可以在调用实人认证接口之前,使用以下方法进行定制。
    configuration.shouldWaitResult = YES;
    注意 上述配置只适用于startByNative接口。如果需要配置start接口,请在实人认证控制台进行操作。
  • 退出时弹窗确认
    如果您需要在用户操作关闭按钮时显示确认弹窗,以防止用户误触,可以在调用实人认证接口之前,使用以下方法进行定制。
    RPSDK.configuration.shouldAlertOnExit = YES;
    说明 使用push方式弹出时,请确认当前viewControllernavigationController属性不为空。
  • 活体检测幅度提示颜色
    活体检测默认的幅度提示颜色为蓝色(过程中)和绿色(成功)。如果您需要定制活体检测幅度提示颜色,可以在调用实人认证接口之前,使用以下方法进行定制。
    RPSDK.configuration.intermediateProgressColor = UIColor.orangeColor; //活体检测幅度提示颜色(过程中)设置为橙色。
    RPSDK.configuration.successfulProgressColor = UIColor.redColor; //活体检测幅度提示颜色(成功)设置为红色。
  • 页面图标
    实人认证可以定制的图标包括:关闭按钮、声音开启和关闭按钮、确认按钮。如果您需要定制以上按钮的图标,可以在调用实人认证接口之前,使用以下方法进行定制。
    //关闭按钮图标设置,像素设置为40*40。
    RPSDK.configuration.exitIcon = [UIImage imageNamed:@"custom_icon"]; 
    //声音开启图标设置,像素设置为40*40。
    RPSDK.configuration.soundOnIcon = [UIImage imageNamed:@"custom_icon"]; 
    //声音关闭图标设置,像素设置为40*40。
    RPSDK.configuration.soundOffIcon = [UIImage imageNamed:@"custom_icon"]; 
    //确认按钮图标设置,像素设置为761*114。
    RPSDK.configuration.confirmButtonIcon = [UIImage imageNamed:@"custom_icon"]; 
  • 实人认证过程回调
    实人认证提供了不同阶段的回调方法,方便您在不同阶段进行定制。
    /**
     NS_ENUM(NSInteger, RPPhase)
     实人认证阶段
     */
    typedef NS_ENUM(NSInteger, RPPhase) {
    
        /**
         活体检测即将开始
         */
        RPPhaseBiometricsWillStart,
    
        /**
         活体检测已经开始
         */
        RPPhaseBiometricsDidStart,
    
        /**
         活体检测成功
         */
        RPPhaseBiometricsDidSucceed,
    
        /**
         活体检测失败
         */
        RPPhaseBiometricsDidFail,
    
        /**
         提交服务端认证开始
         */
        RPPhaseVerificationDidStart,
    
        /**
         提交服务端认证结束
         */
        RPPhaseVerificationDidFinish,
    };
    如果您需要定制上述功能,可以调用以下接口。
    /**
    开始实人认证,适用于纯Native的认证方案。
    只支持纯人脸的登录、解锁、认证功能,纯H5方案不支持此方法。
    
     @param verifyToken 实人认证流程的唯一标识,一般从接入方自己的服务端获取,有效时间30分钟。
     @param viewController 调用实人认证的视图控制器。
     @param transitionStyle 页面跳转方式。
     @param progress 实人认证过程回调。
     @param completion 实人认证结果回调。
     */
    + (void)startByNativeWithVerifyToken:(NSString *)verifyToken
                          viewController:(UIViewController *)viewController
                         transitionStyle:(RPTransitionStyle)transitionStyle
                                progress:(RPProgress _Nullable)progress
                              completion:(RPCompletion _Nullable)completion;

错误码说明

在实人认证completion的RPResult中可获取到认证状态和认证失败错误码。具体说明请参见下表。

State ErrorCode ErrorCode释义
RPStatePass 1 认证通过。
RPStateFail 2~12 表示认证不通过,具体的原因可以查看服务端的查询认证结果接口文档(DescribeVerifyResult)中认证状态的说明。
RPStateNotVerify -1 未完成认证,原因:用户在认证过程中主动退出。
-10 未完成认证,原因:设备问题,如设备无摄像头、无摄像头权限、摄像头初始化失败、当前手机不支持端活体算法等。
-20 未完成认证,原因:端活体算法异常,如算法初始化失败、算法检测失败等。
-30 未完成认证,原因:网络问题导致的异常,如网络链接错误、网络请求失败等,需要您检查网络并关闭代理。
-40 未完成认证,原因:SDK异常,如SDK初始化失败、SDK调用参数为空、活体检测被中断(如电话打断)等。
-50 未完成认证,原因:用户活体失败次数超过限制。
-60 未完成认证,原因:手机的本地时间和网络时间不同步。
-10000 未完成认证,原因:客户端发生未知错误。
3001 未完成认证,原因:认证Token无效或已过期。
3101 未完成认证,原因:用户姓名身份证实名校验不匹配。
3102 未完成认证,原因:实名校验身份证号不存在。
3103 未完成认证,原因:实名校验身份证号不合法。
3104 未完成认证,原因:认证已通过,重复提交。
3203 未完成认证,原因:设备不支持刷脸。
3204 未完成认证,原因:非本人操作。
3206 未完成认证,原因:非本人操作。
3208 未完成认证,原因是:公安底照不存在。

常见问题

请参见iOS集成常见问题