文档

iOS接入

更新时间:

刷脸认证提供iOS客户端SDK,帮助您在业务应用(App)中实现刷脸认证功能。您可通过刷脸认证的服务端认证初始化接口,获取刷脸认证唯一标识CertifyId,并使用CertifyId唤起刷脸认证客户端SDK。本文将结合示例代码进行iOS客户端接入的详细说明。

前提条件

  • 刷脸认证应用必须运行在iOS 9.0及以上版本的系统上。

  • 您的业务应用必须采用Objective C++或Swift集成金融级实人认证服务。

说明

iOS接入不支持模拟器模式调试。

配置开发环境

  1. info.plist中配置摄像头和麦克风权限请求(仅金融级多因子意愿认证方案需配置麦克风权限)。

    image

  2. 在Xcode的编译设置中关闭Enable Bitcode选项。

    ios-开发环境配置2

  3. 在Xcode编译设置的Linking > Other Linker Flags中,添加设置-ObjC

    若您使用Xcode 15进行编译,还需添加Id64

    配置

    如果您的工程设置了-force_load选项,则需要加入-force_load <framework path>/AliyunOSSiOS,命令之间以空格隔开,例如-ObjC -force_load <framework path>/AliyunOSSiOS

配置依赖

  1. 下载iOS SDK

    该SDK为framework包。您需要在Xcode添加Link Binary With Libraries、SDK中的12个包和额外系统库依赖。

  2. 解压下载的SDK包,并在解压的文件夹中执行以下命令提取所有的framework到Products目录。

    for i in $(ls *.tgz);do tar xvf $i;done
    • SDK中的包:

      AliyunFaceAuthFacade.framework
      APBToygerFacade.framework
      APPSecuritySDK.framework
      BioAuthEngine.framework
      faceguard.framework
      DTFIdentityManager.framework
      DTFUtility.framework
      MultiFactorFacade.framework
      OCRDetectSDKForTech.framework
      ToygerNative.framework
      ToygerService.framework
    • 系统库依赖:

      CoreGraphics.framework
      Accelerate.framework
      SystemConfiguration.framework
      AssetsLibrary.framework
      CoreTelephony.framework
      QuartzCore.framework
      CoreFoundation.framework
      CoreLocation.framework
      ImageIO.framework
      CoreMedia.framework
      CoreMotion.framework
      AVFoundation.framework
      WebKit.framework
      libresolv.tbd
      libz.tbd
      libc++.tbd
      libc++.1.tbd
      libc++abi.tbd
      AudioToolbox.framework
      CFNetwork.framework
      MobileCoreServices.framework
      libz.1.2.8.tbd
      AdSupport.framework
      ReplayKit.framework

拷贝资源文件

选择TARGETS,单击Build Phases页签,在Copy Bundle Resources中添加以下bundle:

  • APBToygerFacade.bundle:位于APBToygerFacade.framework中。

  • ToygerService.bundle:位于ToygerService.framework中。

  • OCRXMedia.bundle:位于OCRDetectSDKForTech.framework中。

  • BioAuthEngine.bundle:位于BioAuthEngine.framework中。

  • MultiFactorFacade.bundle:位于MultiFactorFacade.framework中。

  • APBToygerFacadeSuitable.bundle:位于APBToygerFacade.framework中。

image.png

调用SDK

  1. 引入头文件。

    命令如下:

    #import <AliyunFaceAuthFacade/AliyunFaceAuthFacade.h>
  2. 初始化SDK。

    说明

    为了提升用户体验并为刷脸认证准备一些必备的数据,iOS客户端需要初始化SDK。您可以在调用appDelegate函数时(如下列代码所示)放置初始化SDK代码。您也可以在获取metaInfo数据前(如步骤3所示)放置初始化SDK代码。

    appDelegate函数调用,示例代码:

    - (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions {
        [AliyunFaceAuthFacade initSDK];// 初始化SDK。
    }

    IPv6网络初始化,示例代码如下:

    - (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions {
        [AliyunFaceAuthFacade initIPv6];// 初始化SDK。
    }
  3. 获取metaInfo数据。

    示例代码如下:

    [AliyunFaceAuthFacade initSDK];// 初始化SDK,如果已经在appDelegate函数中调用过,此处无需再重复调用。
    [AliyunFaceAuthFacade getMetaInfo];

    IPv6网络初始化,示例代码如下:

    [AliyunFaceAuthFacade initIPv6];// 初始化SDK,如果已经在appDelegate函数中调用过,此处无需再重复调用。
    [AliyunFaceAuthFacade getMetaInfo];
    说明

    返回值类型是NSDictionary,您的服务端需要将其转换为JSON字符串。调用服务端发起认证请求接口时,在入参metaInfo中传入该值。关于发起认证请求的具体操作,请参见发起认证请求

  4. 调用SDK开始认证。

    示例代码如下:

    [AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];

    参数说明如下表所示。

    名称

    类型

    描述

    certifyId

    NSString

    您可以通过服务端发起申请请求接口获取该参数。关于发起认证请求的具体操作,请参见发起认证请求

    extParams

    NSDictionary

    通过以下代码传入当前viewController,用于展现网络加载和presentViewController

    [extParams setValue:self forKey:@"currentCtr"];
    • 如需设置OCR的下一步按钮的颜色,在extParams中添加按钮的正常颜色和按钮按下时的颜色。代码示例如下:

      [extParams setValue:@"00FF00" forKey:ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_COLOR];
      [extParams setValue:@"0000FF" forKey:ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_CLICKED_COLOR];
    • 如需设置扫脸时的圆圈颜色,在extParams中添加圆圈颜色。代码示例如下:

      [extParams setValue:@"FF0000" forKey:ZIM_EXT_PARAMS_KEY_OCR_FACE_CIRCLE_COLOR];
    • 如需返回本地视频,在extParams中添加returnVideo,并且设置值为true。代码示例如下:

      [extParams setValue:@"true" forKey:@"returnVideo"];
    • 如需服务端查询接口返回视频,需要额外在extParams中添加ZIM_EXT_PARAMS_KEY_USE_VIDEO_UPLOAD,并且设置值为true。代码示例如下:

      [extParams setValue:@"true" forKey:ZIM_EXT_PARAMS_KEY_USE_VIDEO_UPLOAD]
      说明

      金融级实人认证支持设置返回活体检测的视频,默认设置为不返回。如果设置为返回,在您使用金融级实人认证SDK完成认证(不区分认证结果为F或T),并在SDK回调和查询接口时返回视频路径,请您及时处理。

    • 如需自定义X号(页面关闭按钮),您可以参照以下步骤:

      • 如需自定义X号的图片,需要额外在extParams中添加cancelImage,并设置值为UIImage。代码示例如下:

        [extParams setValue:UIImage forKey:@"cancelImage"];
      • 如需自定义X号的图片位置,需要额外在extParams中添加imageOrientation,并设置值为rightleft 。默认为left。代码示例如下:

        [extParams setValue:@"right" forKey:@"imageOrientation"];

    更多UI自定义设置,请参见iOS SDK UI自定义配置说明

    返回结果说明:

    [AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];

    response.code包含以下返回参数,具体说明如下表所示。

    错误码

    错误码文案

    错误码描述

    1000(ZIMResponseSuccess)

    刷脸成功

    用户完成了刷脸过程,认证建议结果为通过。该结果仅供参考,可通过调用服务端DescribeFaceVerify接口获取最终认证结果。

    1001(ZIMInternalError)

    系统错误

    表示系统错误。

    1003(ZIMInterrupt)

    验证中断

    表示验证中断。

    2002(ZIMNetworkfail)

    网络错误

    表示网络错误。

    2003(ZIMTIMEError)

    客户端设备时间错误

    表示客户端设备时间错误。

    2006(ZIMResponseFail)

    刷脸失败

    用户完成了刷脸过程,认证建议结果为未通过。该结果仅供参考,可通过调用服务端DescribeFaceVerify接口获取最终认证结果、未通过的详细原因。

    说明

    关于错误码的更多信息,请参见金融级客户端iOS错误码详情

    代码示例:

    [AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {
             dispatch_async(dispatch_get_main_queue(), ^{
                 NSString *title = @"刷脸成功";
                 switch (response.code) {
                     case ZIMResponseSuccess://1000。
                         break;
                     case ZIMInterrupt://1003。
                         title = @"用户退出";
                         break;
                     case ZIMNetworkfail://2002。
                         title = @"网络错误";
                         break;
                     case ZIMTIMEError: //2003。
                         title = @"设备时间设置不对";
                         break;
                     case ZIMResponseFail: //2006。
                         title = @"刷脸失败";
                         break;
                     case ZIMInternalError://1001。
                         title = @"初始化失败";
                         break;
                     default:
                         break;
                 }
             });
        }];

Demo代码包

您可以下载以下iOS Demo代码包进行体验。在使用过程中,请替换iOS Demo代码包中的文件的版本为最新的版本:

SDK包大小裁剪说明

更多说明,请参见SDK包裁剪说明