IOS—方案集成指南(升级)

前言

【本文】方案集成指南适用于需要集成APP方案，实现权威数据源核验、自传照片人脸比对、仅活体检测这3个业务需求时来参考。百度人脸实名认证APP方案默认开启大数据风控功能，即使用人脸识别V4系列API接口接受SDK端传入本地环境扫描的设备指纹及安全信息，并基于百度海量大数据设备因子，对SDK端进行设备风险识别，辨别是否为⻛险设备、并返回识别结果。此方案可有效防御黑产批量虚拟机、病毒侵入等攻击手段，降低第三方黑产攻破概率，提升业务安全性。

特殊的，如果控制台大数据风控选项设定“关闭”，则需要配合开通人脸识别V3系列API接口实现权威数据源核验、自传照片人脸比对、仅活体检测这3个业务需求。

快速定位

• 人脸实名认证（权威数据源核验）实现方式
• 人脸比对（自传图片）
• 仅活体检测实现方式
• 核验及计费结果获取，服务端接口

1. 文档说明

2. 版本说明

3. SDK说明

注：获取SDK可参考：获取示例工程

4. 运行项目工程

4.1 打开下载的iOS示例工程

如下图所示：

4.4 确认bundleId等信息是否正确

连接真机进行运行，之后可以看到如下界面：

4.5 点击开始身份认证

测试示例工程是否跑通，之后扫码身份证或输入身份证信息后，点击进行身份核验，验证成功可以看到如下界面：

上图为示例工程运行成功，之后可以将示例工程代码集成到目标项目中。

5. 集成步骤

5.1 将BDFaceSDK或BDFaceIDLSDK文件夹下所有文件拖动到目标项目中

如下图所示

5.2 将BDFaceLogicLayer.framework、AipBase.framework、 AipOcrSdk.framework和IdcardQuality.framework拖动到目标项目

如下所图示

5.3 在Build Phases中点击下面的+号

选择NewCopyFilePhases,添加一个CopyFiles（可重新命名为Embed）

5.4 双击CopyFiles

改为Embed Frameworks，同时Destination改为framework，之后将AipBase.framework、AipOcrSdk.framework和IdcardQuality.framework 拖动到下面

5.5 Link Binary With Libraries中添加libc++.tbd、libz.tbd 和 对应的framework

如下图所示:

5.6 确认添加的库文件设置正确

如下图所示，点击general, 这三个库需要为Do Not Embed：BDFaceBaseKit.framework, BDFaceLogicLayer.framework，CoreTelephony.framework.

5.7 info.plist 文件中添加以下key（获取相机和照片权限）

最后之后可以将人脸核验示例工程代码代码结合自身工程项目，将相关代码集成到目标工程中。

6. 人脸初始化接口（SDK）

设置默认参数（动作活体参数，人脸配置参数，UI参数）

Step 1: 初始化人脸和OCR SDK

- (void)initFaceServiceAndInfoCollectService

Step 2: 初始化人脸SDK，进行参数配置。其中涉及活体方案相关的参数配置示例如下

- (void)initFaceSDK
  /// 采集SDK初始化参数
  [BDFaceBaseKitManager sharedInstance].paramsCustomConfigItem.isLivenessType = YES; //是否开启动作活体
  [BDFaceBaseKitManager sharedInstance].paramsCustomConfigItem.isColorType = YES; //是否开启炫彩活体
 
 //如果想实现更精细的活体方案配置
  @property (nonatomic, assign) int     numOfLiveness;                    //  活体动作池中有几个动作 （动作选取）
  @property (nonatomic, assign) int     actionLiveSelectNum;              //  需要从动作活体动作池中抽取几个动作（动作数量）
  @property (nonatomic, strong) NSMutableArray  *liveActionArray;         //  动作活体列表
  

入参说明

initFaceBlock中，使用以下函数进行人脸SDK初始化 -(void)initCollectWithLicenseID:(NSString )licenseID andLocalLicenceName:(NSString )licenseName andExtradata:(NSDictionary *)extradata callback:(FaceSDKInitResultBlock )block;

回调状态码说明

具体枚举值如下

授权文件相关逻辑

人脸识别授权文件（idl-license.face-ios），OCR身份证识别授权文件（aip.license），从console平台下载完iOS项目，这些文件即包括在下载的示例项目中，不需要特殊处理，按上面第5.3步整体拖入目标项目中即可。

如果您下载集成方案的物料为控制台，此处可忽略；鉴权文件配置已自动生效。

配置授权信息： 导入license文件后，需配置FACE_LICENSE_NAME、FACE_LICENSE_ID等信息:

具体参数使用请参照示例demo。

license文件使用注意事项：如出现鉴权失败无法调用人脸采集，请检查license id与license文件导入及配置是否正常。

（1）license id需要注意-face-ios后缀是否添加。

（2）如存在多种环境配置，请确保每个环境下的license id与license文件一一对应。tip：license文件存在运行缓存，切换测试环境请清空缓存，删除安装包后重新编译安装。

（3）确保license文件路径访问正常。

（4）如出现网络鉴权失败等提示，说明license文件与FACE_LICENSE_NAME未正确设置，请才考接入demo检查工程环境，确保参数无误。

7. 获取verify_token接口（服务端）

本接口为实名认证APP方案的verify_token获取接口，利用所获取的verify_token进行实名认证流程的有效期为2小时。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/verifyToken/generate

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求参数：

• 请求示例

  {
  "match_source": 0, //以权威数据源核验场景为例，需要传入0
  "plan_id": 16144,
  }

返回参数

• 返回结果

• 返回示例

  {
      "success": true,
      "result": {
          "verify_token": "Yz9rWITm4vak16PBAh5x8oG7"
      },
      "log_id": "1814798895"
  }

8. 人脸实名认证实现方式

实现方式请参考如下时许图

8.1 指定用户信息上报接口（服务端）

本接口用于，控制台APP方案中选择身份信息录入方式为业务调用时传入，需要先调用此接口输入指定用户的姓名+身份证号信息，再继续请求 人脸权威数据源核验接口（SDK）

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL：https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/idcard/submit

URL参数：

Header：

Body中放置请求参数，参数详情如下：

• 请求示例：

{
    "verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
    "id_name": "张三",
    "id_no": "500***********3390",
    "certificate_type": 0            // 证件类型：0:大陆居民二代身份证,4:港澳台居民居住证
}

返回参数

• 返回结果

• 返回示例

  {
      "success": true,
      "result": 1,
      "log_id": "1244068892"
  }

8.2 人脸权威数据源核验接口（SDK）

基于姓名、身份证号、当前SDK获取的人脸图片，与公安权威数据源进行对比，并得出比对分数，并基于此进行业务判断是否为同一人。包含活体检测、质量检测、实名认证功能，可通过传入参数进行控制，如您的业务场景核心为实名认证，无需重复请求 7.4 人脸活体检测 接口。

入参dic值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

  {
    "error_code": 0, //代表通过了百度内部的核验规则，建议使用服务端查询接口获得真实结果做业务判断
     "log_id": "1790651229035123218"
  }

9. 人脸对比（自传照片）实现方式

实现方式请参考如下时许图

9.1 对比图片上传接口（服务端）

本接口适用于人脸比对（自传照片）业务场景，为了保证用户信息安全，您需要提前通过服务端请求本接口来上报比对人脸信息。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/uploadMatchImage

URL参数：

Header：

Body中放置请求参数，参数详情如下：

• 请求示例：

  {
    "verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/",
    "quality_control" : "LOW",
    "liveness_control" : "LOW",
  }

返回参数

• 返回结果

• 返回示例

  {
    "success": true,
    "result": null,
    "log_id": "1329130892"
  }

9.2 人脸对比（SDK）

包含活体检测、质量检测、人脸1:1识别功能，可通过传入参数进行控制，如您的业务场景核心为人脸对比（自传照片），无需重复请求 7.4 人脸活体检测 接口。

入参dic值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

  {
    "error_code": 0, //代表通过了百度内部的核验规则，建议使用服务端查询接口获得真实结果做业务判断
     "log_id": "1790651229035123218"
  }

10. 人脸活体检测实现方式

实现方式请参考如下时许图

10.1 活体检测（SDK）

包含本地活体加云端活体，本地活体分静默活体、炫瞳活体、动作活体三种，云端活体可以判断图片中的人脸是否为二次翻拍以及是否为合成图攻击。实现二次验证采集图片是否存在假体攻击破绽的情况。
如您的业务场景核心为人脸实名认证（权威源），请直接参考 7. 人脸实名认证实现方式。

入参dic值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

  {
    "error_code": 0, //代表通过了百度内部的核验规则，建议使用服务端查询接口获得真实结果做业务判断
     "log_id": "1790651229035123218"
  }

  
  

11. 验证后查询接口

11.1 获取认证人脸接口（服务端）

本接口返回进行人脸实名认证过程中进行认证的最终采集的人脸信息。根据Verify_token返回的结果信息会在云端保留3天，您可根据需要在此期间进行调取查询。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/simple

URL参数：

Header：

Body中放置请求参数，参数详情如下：

• 请求示例：

{
  "verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

  {
      "success": true,
      "result": {
          "image":"https://brain.baidu.com/solution/faceprint/image/query?verify_token=xxxxxx"
      },
      "log_id": "1054986003"
  }

  br

11.2 核验及计费信息获取（服务端）

根据Verify_token返回的信息会在云端保留3天，您可根据需要在此期间进行调取查询。

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

在线调试

您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。

请求说明

注意事项：

• 请求体格式化：Content-Type为application/json，通过json格式化请求体。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/getall

URL参数：

Header：

Body中放置请求参数，参数详情如下：

请求示例：

{
   "verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}

返回参数

• 返回结果

• 返回示例

{
    "success": true,
    "result": {
        "verify_count": 1,
        "ocr_charge_count": 0,
        "match_charge_count": 0,
        "verify_charge_count": 1,
        "verify_result": [
            {
                "order": 1,
                "code": "0",
                "message": "核验成功",
                "is_verify_passed": true,
                "verify_time": "2024-04-02 16:15:01",
                "is_charged": true,
                "charge_type": "verify",
                "charge_time": "2024-04-02 16:15:01",
                "is_ocr_charge": false,
                "ocr_count": 0,
                "ocr_charge_time": null,
                "verify_detail": {
                    "score": 84.4000015258789,
                    "threshold": 80.0,
                    "app": true,
                    "face_image": "https://bj.bcebos.com/v1/mingjing-qa/hb/h5-video-temp/temp/202404/16130/ZWCCBxXUz48Q9wuR/Igi1n0SpQRtzm9ySWLQwdwvn-00.jpg?authorization=bce-auth-v1%2F89e9208d0d5a497cbc8922a4d74d4f71%2F2024-04-02T08%3A19%3A23Z%2F86400%2F%2Fb3abf9eef0b7f897ccf0350d7d59bbfd4498ab214ef73d437a45e319e5028688",
                    "verify_log_id": "1775074433891895605",
                    "liveness_score": 0.99999183,
                    "spoofing_score": null,
                    "risk_level": null,
                    "risk_tag": null,
                    "is_demote": false
                },
                "idcard_confirm": {
                    "name": "李跃坤",
                    "idcard_number": "140522199804101534",
                    "idcard_type": "0",
                    "idcard_ocr_result": null,
                    "idcard_images": null
                }
            }
        ]
    },
    "log_id": "1775075543214005842"
}

12. OCR身份证识别相关接口

12.1 OCR身份证识别初始化接口

入参说明

注：如果aip.license文件鉴权文件正确，那么可以使用OCR识别成功识别身份证信息。

12.2 OCR身份证识别接口

支持对二代居民身份证字段进行结构化识别，包括姓名、性别，调用参考OCR身份证识别接口文档。

参数值列表如下：

config配置说明

权限

只使用人脸采集功能，不使用OCR

• 运行示例工程代码

点击开始身份核验，走完所有流程，可以出现如下界面：

• 删除库文件：AipOcrSdk.framework，AipBase.framework，IdcardQuality.framework**
• 全局搜索与AipOcrSDK/AipOcrSdk.h

找到后并删除项目中所有引入对应SDK的代码，也可以注释，在删除后可能导致编译不通过，可以根据报错部分保证正常功能不受影响的同时进行相应的代码注释。

• 全局搜索 -(void) startOCRSdk 并注释该函数

注意：其他编译报错部分调用的地方也需要注释或删除

  // 打开相机扫描
     - (void)startOCRSdk {
    [self configCallback];
    // 身份证识别
    [AipCaptureCardVC clearIdCard];
    BDAipOCRConfig *config = [[BDAipOCRConfig alloc] init];
    AipNavigationController *detectNavi = [AipCaptureCardVC viewControllerToDetectIdCard:config
                                                 handler:^(UIImage *image) {
        _idCardImage = image;
        [[AipOcrService shardService] detectIdCardFrontFromImage:image
                                                     withOptions:nil
                                                  successHandler:^(id result) {
            _successHandler(result);
        } failHandler:_failHandler];
    }];
    UIViewController *detectRoot = [[UIViewController alloc] init];
    detectRoot.view.backgroundColor = [UIColor whiteColor];
    detectRoot.view.clipsToBounds = YES;
    [detectRoot addChildViewController:detectNavi];
    [detectRoot.view addSubview:detectNavi.view];

    [self.navigationController pushViewController:detectRoot animated:YES];

    _vc = detectRoot;
    __weak typeof(detectRoot) weakDetectRoot = detectRoot;
    detectNavi.captureController.backAction = ^{
        [weakDetectRoot.navigationController popViewControllerAnimated:YES];
    };}

• 编译运行代码首页并将身份证OCR功能关闭或者使用代码

   // 身份证获取方式   1 OCR扫描    0  手动输入  2代码传
    + (int)useOCR {
    BDConfigDataService *service = [self sharedInstance];
    NSNumber *value = service.sharedDic[BDConfigDataServiceKeyForSettingOcr];
    if (value) {
        return value.intValue;
    }
    return [[BDConfigFileParser sharedInstance] useOCR];}

• 将userOCR的值设置为0

保证程序只能手动输入身份信息来调用人脸，此部分功能模块不使用也可以对应删除。

运行工程

常见问题

verify_token的详细说明

（1）access_token 有效期为 30 天，重复生成 access_token 的话，对之前的不影响，依旧能使用；access_token 与verify_token 是包含关系，即 verify_token 是由 access_token生成的，如果一个 verify_token 是和一个不匹配的 access_token 使用，会提示“Token无效或者已过期”

（2）verify_token 的核验有效期为 2 小时，在有效期内可以进行了核验动作，如果超过了 2 小时没有使用该 token 进行核验的话会提示“Token无效或者已过期”

（3） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），无法再进行核验，如果再次进行核验，会提示“Token无效或者已过期”

（4） verify_token 核验完毕后（核验成功，或设置了认证未通过时URL失效），支持对后验接口的查询，有效期均为 3 天，3 天后再次查询后验接口，会提示“Token无效或者已过期”

获取认证人脸、查询认证结果、核验及计费信息获取接口持续返回错误码18，提示openapi限制，且有返回logid

答：检查APP方案依赖的“人脸实名认证V3/V4”、“人脸对比V3/V4”、“在线图片活体检测V3/V4” 三项付费接口，是否有免费额度，或者直接开通后付费，以消除该报错提示。开通后，再进行重试。