获得离线活体检测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,默认只有短期试用授权的活体检测功能。如果您需要购买活体检测功能的正式授权(有效期授权或永久授权),您可以联系阿里云客户经理进行咨询和开通。

背景信息

下载离线活体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
    SGSecurityBody.framework
    SNN
    VerifyFaceSDK.framework
  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)对称加密,密钥长度128字节。
       */
      + (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;

SDK包体积优化

从实人认证控制台下载到的SDK默认包含了所有算法模型,所以包体积较大。为了对包体积进行优化,离线活体检测SDK提供了模型动态下载的能力。

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

支持下载的模型:翻拍模型model_live.bin

找到FaceLivenessSDK.bundle资源包,右击显示包内容,在models目录下可以看到几个模型文件(.bin后缀),选中model_live.bin(翻拍模型)然后删除。在调用活体检测之前调用预加载模型接口preLoadModel,此接口是后台异步操作,不阻塞主线程,为了更好的用户体验,建议在应用启动时调用,代码示例如下:

/**
 预加载模型,如果你为了降低包体积本地没有内置模型,所以需要远程加载模型,在模型没有更新的时候只需要加载一次即可。
 建议应用启动时调用,后台异步任务,不阻塞线程。
 */
+ (void)preLoadModel;

// 调用预加载接口。
[Aligreen preLoadModel];

UI定制

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

错误码说明

错误代码说明
0成功
-1未完成认证,原因:用户在认证过程中主动退出。
-10未完成认证,原因:设备问题,如设备无摄像头、无摄像头权限、摄像头初始化失败、当前手机不支持端活体算法等。
-20未完成认证,原因:端活体算法异常,如算法初始化失败、算法检测失败等。
-30未完成认证,原因:网络问题导致的异常,如网络链接错误、网络请求失败等,需要您检查网络并关闭代理。
-40未完成认证,原因:SDK异常,如SDK初始化失败、SDK调用参数为空、活体检测被中断(如电话打断)等。
-50未完成认证,原因:用户活体失败次数超过限制。
-1005执行动作数量超标。
说明 最多执行两个动作。
-1007参数错误,一般用于前置拦截校验。
-10091v1能力未授权,并未开通 1v1比对功能。
-1010算法初始化失败或者模型不存在。
-1011算法识别失败。
5000授权错误。
5001输入参数有误,例如envctxlicenseData参数为空等。
5002licenseData参数格式错误。
5003签名校验失败。
5004包名称校验失败。
5005公钥校验失败。
5006授权过期。
5007未执行授权检查。
5008iOS BundleID校验错误。
5009终端标识校验错误。
5010授权过期且日期被修改。