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

注意 亲爱的用户:

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

前提条件

已获取正确的iOS SDK。
  • iOS SDK与BundleID绑定。如果SDK与BundleID不一致,则需要在实人认证控制台上重新下载SDK。
  • 如果您使用的是3.0.0之前的旧版本SDK,您可以将其升级到3.0.0版本,具体操作请参见iOS SDK升级指南(3.3.0)

在工程中导入SDK

  1. 在您的项目工程中导入实人认证依赖包。
    解压实人认证SDK后,将以下依赖包导入到您的项目工程中,导入时必须勾选Copy items if needed,表示自动复制一份相同的文件到工程中,并引用复制后的文件在工程目录中的位置。
    AliyunOSSiOS.framework
    RPSDK.framework
    SecurityGuardSDK.framework
    SGMain.framework
    SGSecurityBody.framework
    说明 集成实人认证SDK后,应用大小的增量为2.89Mb。
  2. 在您的工程中添加以下实人认证需要的系统依赖库。
    CoreMotion.framework
    CoreTelephony.framework
    Libc++.tbd
    Libresolv.tbd
    Libz.tbd
    SystemConfiguration.framework
    导入的依赖包
    完成以上两个步骤后,您可以在Build Phases > Link Binary With Libraries看到导入的依赖包。如果未看到依赖包,说明导入过程中出现问题,请确认将所有依赖包拷贝到工程项目,并勾选正确的应用目标。
  3. 导入以下资源文件。导入时必须勾选Copy items if needed,表示自动复制一份相同的文件到工程中,并引用复制后的文件在工程目录中的位置。
    yw_1222_0769.jpg
    RPSDK.bundle
    signaturepic
    导入完成后,您可以在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和result.message来区分(详见错误码说明)。
                break;
        }           
    }];
  • 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和result.message来区分(详见错误码说明)。
            break
        default:
            break
        }
    }
方式二: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和result.message来区分(详见错误码说明)。
                break;
        }
    }];
  • 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和result.message来区分(详见错误码说明)。
            break
        default:
            break
        }
    }

可选配置

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

配置选项接口在RPConfiguration.h文件中。在调用实人认证之前,您必须先创建实人认证配置实例,示例代码如下:
RPConfiguration *configuration = [RPConfiguration configuration];
  • 提示声音默认开关
    在活体检测过程中,默认开启提示声音,例如“眨下眼”、“左右摇头”等。如果您需要默认关闭提示音,可以在调用实人认证接口之前,使用以下方法进行定制。
    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; //活体检测幅度提示颜色(成功)设置为红色。
  • 页面图标
    实人认证可以定制的图标包括:关闭按钮、声音开启和关闭按钮、确认按钮。如果您需要定制以上按钮的图标,可以在调用实人认证接口之前,使用以下方法进行定制。
    RPSDK.configuration.exitIcon = [UIImage imageNamed:@"custom_icon"]; //关闭按钮图标设置。
    RPSDK.configuration.soundOnIcon = [UIImage imageNamed:@"custom_icon"]; //声音开启图标设置。
    RPSDK.configuration.soundOffIcon = [UIImage imageNamed:@"custom_icon"]; //声音关闭图标设置。
    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 -2 未完成认证,原因是:网络请求失败,场景与调用接口不符或者接入错误(请参见result.message)。
-1 未完成认证,原因是:用户在认证过程中主动退出。
3001 未完成认证,原因是:认证token无效或已过期。
3101 未完成认证,原因是:用户姓名身份证实名校验不匹配。
3102 未完成认证,原因是:实名校验身份证号不存在。
3103 未完成认证,原因是:实名校验身份证号不合法。
3104 未完成认证,原因是:认证已通过,重复提交。
3204 未完成认证,原因是:非本人操作。
3206 未完成认证,原因是:非本人操作。
3208 未完成认证,原因是:公安网没有留存身份证照片。

常见问题

请参见iOS集成常见问题