获得离线活体检测SDK后,您可以参考本文指导将SDK集成到您的iOS应用中。

前提条件

已获取正确的iOS SDK。
说明 iOS SDK与iOS应用包的BundleID绑定。如果您获取的iOS SDK包与iOS应用包的BundleID不一致,请重新下载正确的iOS SDK包。更多信息,请参见下载离线SDK

关于离线活体SDK产品功能的详细说明,请参见离线活体检测SDK

使用说明

  • SDK联网说明

    如果您购买的SDK License非永久有效(例如有效期是1年),那么您的终端用户在使用扫脸功能时手机设备必须连接网络;如果您购买的SDK License永久有效,那么SDK是纯离线的模式,您的终端用户在使用扫脸功能时手机设备可以不连接网络。

  • SDK功能说明

    只有SDK版本为4.13.1版本及以上,才同时具备活体检测(终端用户做动作活体并进行翻拍检测后采集到活体人脸图片)和人脸1:1比对能力。人脸1:1比对能力是在4.13.1版本新增的,低于该版本的只具备活体检测功能。

    当您从实人认证控制台下载到的SDK,默认只有短期试用授权的活体检测功能,不具备人脸1:1功能的使用授权。如果您需要购买活体检测功能的正式授权(有效期授权或永久授权),或购买人脸1:1功能的使用授权,您可以联系阿里云客户经理进行咨询和开通,或者通过工单联系我们。

背景信息

下载离线活体SDK后,您可参考以下步骤将SDK集成到您的iOS应用中。

说明 iOS SDK与BundleID绑定,不同BundleID需要在实人认证控制台

在工程中导入SDK

  1. 导入离线活体依赖包。
    解压离线活体检测SDK,并将以下iOS的依赖包引入到您的项目工程中。导入时必须勾选Copy items if needed,表示自动复制一份相同的文件到工程中,并在工程目录中的位置引用复制后的文件。
    Aligreen.framework
    MNN.framework
    libcrypto.a
    libssl.a
    SecurityGuardSDK.framework
    SGMain.framework
    SGNoCaptcha.framework
    SGSecurityBody.framework
    SNN
  2. 在您的工程中添加以下离线活体检测需要的系统依赖库。
    CoreMotion.framework
    CoreTelephony.framework
    Libc++.tbd
    Libz.tbd
    SystemConfiguration.framework
    完成以上两个步骤后,您可以在Build Phases > Link Binary With Libraries看到导入的依赖包。如果未看到依赖包,说明导入过程中出现问题,请确认将所有依赖包拷贝到工程项目,并勾选正确的应用目标。依赖包
  3. 导入以下资源文件。
    导入时必须勾选Copy items if needed,表示自动复制一份相同的文件到工程中,并在工程目录中的位置引用复制后的文件。
    aligreen-license.bin
    FaceLivenessSDK.bundle
    yw_1222_1d41.jpg
    导入完成后,您可以在Build Phases > Copy Bundle Resources看到资源文件。如果未看到资源文件,则说明导入过程中出现问题,请确认将所有资源文件拷贝到工程项目,并勾选正确应用目标。资源文件
  4. 修改编译选项。
    在工程的Build Settings > Other Linker Flags选项中添加-ObjC编译选项

使用SDK

基础能力
  • 活体检测
    1. 设置加密密钥。
      为了返回的图片数据安全,SDK对返回的数据做了一层简单的加密,加密算法是通用的AES(ECB、PKCS7Padding),SDK提供了对应的解密代码,需要您传入加密的密钥,代码如下:
      /**
       设置加密密钥,为了保证数据安全,对于返回的活体数据
      做了基础的加密,密钥由接入方来生成。
       加密算法使用 AES(ECB)对称加密。
       */
      + (void)setSecurityKey:(NSString *)securityKey;
      
      /**
       解密代码。
      */
      - (NSData *)AES_ECB_DecryptWithData:(NSData *)encryptData
      {
          if (!self.securityKey.length) {
              return nil;
          }
          
          NSData *key = [self.securityKey dataUsingEncoding:NSUTF8StringEncoding];
          NSData *retData = nil;
          NSUInteger dataLength = [encryptData length];
          size_t bufferSize = dataLength + kCCBlockSizeAES128;
          void *buffer = malloc(bufferSize);
          bzero(buffer, bufferSize);
          size_t numBytesEncrypted = 0;
          CCCryptorStatus cryptStatus = CCCrypt(kCCDecrypt, kCCAlgorithmAES128,
                                                kCCOptionPKCS7Padding|kCCOptionECBMode,
                                                key.bytes, key.length,
                                                NULL,
                                                encryptData.bytes, encryptData.length,
                                                buffer, bufferSize,
                                                &numBytesEncrypted);
          if (cryptStatus == kCCSuccess) {
              retData = [NSData dataWithBytes:buffer length:numBytesEncrypted];
          }
          free(buffer);
          return retData;
      }
    2. 进行活体检测。

      离线活体检测SDK可以指定零动作、随机一动作、随机二动作进行检测,同时支持指定动作类型。检测成功时,将以图片的形式返回活体检测图片。检测失败时,返回相应错误码。关于错误码的信息,请参见错误码说明

      /**
      如果需要,你可以指定动作类型。
       动作类型列表,最多同时支持两个动作: 1-眨眼、2-张嘴、3-摇头、4-上下点头。
       列表长度不会超过actionCount,超过会被裁剪。
       当detectTypes为空时则为随机动作。
      */
      
      AGNConfiguration *config = [AGNConfiguration configuration];
      config.detectTypes = @[@1, @2];
      config.actionCount = 2;
      
      
      /**
       开始离线活体检测,使用默认配置。
      
       @param viewController 调用活体检测的视图控制器。
       @param completion 活体检测结果回调。
       */
      + (void)startWithViewController:(UIViewController *)viewController
                           completion:(AGNCompletion _Nullable)completion;
      
      /**
       开始离线活体检测。
      
       @param viewController 调用活体检测的视图控制器。
       @param configuration 活体检测配置。
       @param completion 活体检测结果回调。
       */
      + (void)startWithViewController:(UIViewController *)viewController
                        configuration:(AGNConfiguration *)configuration
                           completion:(AGNCompletion _Nullable)completion;
  • 1:1比对能力
    1:1是本地比对能力,通过您传入的一张照片与活体检测返回的图片进行比对得到结果,接口调用如下:
    /**
    如果需要 指定动作类型。
     动作类型列表,最多同时支持两个动作: 1-眨眼、2-张嘴、3-摇头、4-上下点头。
     列表长度不会超过actionCount,超过会被裁剪。
     当detectTypes为空时则为随机动作。
    */
    
    AGNConfiguration *config = [AGNConfiguration configuration];
    config.detectTypes = @[@1, @2];
    config.actionCount = 2;
    
    /**
     开始1:1人脸比对,需具备1:1人脸比对License授权, 图片需清晰,人头像所占整体图片的比例需大于6%。
     */
    + (void)startWithFaceImage:(UIImage *)faceImage
                    controller:(UIViewController *)viewController
                 configuration:(AGNConfiguration *)configuraiton
                    completion:(void(^)(NSInteger score, NSString *resultCode))completion;

SDK包体积优化

SDK自4.13.1版本开始具备活体检测和人脸1:1能力,包含翻拍模型、人脸1:1模型。从实人认证控制台下载到的SDK默认包含了所有算法模型,所以包体积较大(约30 MB)。为了对包体积进行优化,离线活体检测SDK提供了模型动态下载的能力。

说明 如果您购买的是永久授权的License,那么SDK是纯离线的模式,刷脸过程与阿里云服务器没有交互,无法动态下载模型。所以,永久授权license的情况下,SDK必须使用模型内置的方式进行集成,例如接入方需要使用活体采集和人脸1:1,则翻拍模型、1:1模型都需要内置在SDK中集成到业务App里。
目前离线活体检测SDK携带了算法模型,这些算法模型会占用较大的包体积,为了对包体积进行优化,我们提供了模型动态下载的能力,使用该能力需要具备以下前提条件:
  • License非永久授权。
  • 您的终端用户手机设备支持联网,且网络环境良好(不建议在2G、3G这种弱网环境中)。
支持下载的模型:
  • 翻拍模型:model_live.bin
  • 1:1模型:model_feats.bin

如果您的License不支持1:1比对能力(也不会调用到startWithFaceImage:接口),则直接删除 model_feats.bin即可,免得占用SDK包体积。

  1. 选择您需要动态下载的模型并删除不需要的包。
  2. 在调用活体检测或1:1比对能力之前调用预加载模型接口(preLoadModel)。
    /**
     预加载模型,如果你为了降低包体积本地没有内置模型,所以需要远程加载模型,在模型没有更新的时候只需要加载一次即可。
     建议应用启动时调用,后台异步任务,不阻塞线程。
     */
    + (void)preLoadModel;
    
    // 调用预加载接口。
    [Aligreen preLoadModel];

UI定制

离线活体SDK提供了UI定制功能。关于UI定制的详细介绍,请参见UI定制

错误码说明

错误代码 说明
-1001 SDK未初始化。
-1002 获取服务端License失败。
-1003 License已过期。
-1004 License不正确。
-1005 执行动作数量超标。
说明 最多执行两个动作。
5000 授权错误。
5001 输入参数有误,例如envctxlicenseData参数为空等。
5002 licenseData参数格式错误。
5003 签名校验失败。
5004 包名称校验失败。
5005 公钥校验失败。
5006 授权过期。
5007 未执行授权检查。
5008 iOS BundleID校验错误。
5009 终端标识校验错误。
5010 授权过期且日期被修改。