HarmonyOS-方案集成指南（升级）

前言

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

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

快速定位

人脸实名认证（权威源核验）实现方式

人脸比对（自传图片）实现方式

仅活体检测实现方式

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

核验及计费结果获取（服务端）

历史集成方案

1. 文档说明

2. 版本说明

3. SDK说明

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

4. 配置包名和签名

• 从百度云控制台下载鸿蒙Demo之后，首先需要在app.json5中配置鸿蒙应用名称，更新宿主应用的bundleName

• 然后需要在build-profile.json5中配置好宿主应用的签名信息，更新宿主应用的所有签名信息material

5. SDK集成与授权

• 首先在app工程中增加3. SDK说明中的依赖库资源
• 其次将百度云控制台创建应用时获取的人脸授权文件(idl-license.face-harmony)放置于Assets目录下。*//如果集成物料下载渠道为控制台，可忽略

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

初始化接口调用

入参说明

onCallback回调说明

resultCode错误码说明

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 人脸活体检测 接口。

入参params (HashMap类型) key值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

{
  "error_code": 0,  //认证建议结果为通过，该结果仅供参考；可通过调用服务端getall接口获取最终认证结果
  "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 人脸活体检测 接口。

入参params (HashMap类型) key值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

{
  "error_code": 0,  //认证建议结果为通过，该结果仅供参考；可通过调用服务端getall接口获取最终认证结果
  "log_id": "1790651229035123218"
}

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

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

10.1 活体检测（SDK）

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

入参params (HashMap类型) key值列表如下：

onCallback回调说明

resultMap key值列表说明：

• 返回示例

{
  "error_code": 0,  //认证建议结果为通过，该结果仅供参考；可通过调用服务端getall接口获取最终认证结果
  "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"
  }

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. 人脸释放接口（SDK）

人脸释放接口调用，实现对采集功能、模型的释放，减小内存。

13. 人脸采集相关配置（SDK）

人脸相关配置来自于百度云控制台下发的console_config.json文件，详情请参考Demo的BaseFragment类中以下2个方法：
- setFaceQualityConfig()：人脸质量判断相关配置
- faceLiveConfig()：设置活体类型、活体动作
注：不设置，将使用默认值。

// 是否开启炫彩活体能力
faceLiveConfig.setIsOpenColorLive(true);
// 是否开启动作活体能力
faceLiveConfig.setIsOpenActionLive(true);
livenessValueModel = faceLiveConfig.getLivenessValueModel();
//设置活体动作池，如眨眨眼、张张嘴等
for (let i = 0; i < this.consoleConfig.getActions().length; i++) {
  livenessValueModel.actionList.add(this.consoleConfig.getActions()[i]);
}
//设置随机动作数量，实现M选N的随机动作效果
livenessValueModel.actionRandomNumber = this.consoleConfig.getFaceActionNum();

权限

14. 历史集成方案

如果您曾经在控制台创建过人脸实名认证应用与APP方案，希望通过SDK采集获取人脸加密数据，经由服务端转发，配合百度云端接口调用的形式实现实名认证、活体检测及人脸比对的业务流程。可参考如下时许图进行集成与前后端联调：

14.1 修改accessToken

在完成 4.配置包名和签名 后，需要实现动态获取accessToken。

• access_token是是用户的访问令牌，承载了用户的身份、权限等信息。
• 出于安全性考虑，正式环境需要APP服务端通过AK、SK来获取access_token，移动端测试可以链接拼接AK、SK的方式来获取access_token。【此处需要注意】
• access_token存在有效期，正式环境需要APP服务端通过AK、SK来获取access_token，此处只测试使（https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【百度云应用的AK】&client_secret=【百度云应用的SK】）。

14.2 人脸采集及人脸比对接口（无源）

包含本地质量和本地活体，本地质量可以确保采集到的人脸图像符合各条件校验（满足姿态角、光照、模糊度、遮挡等校验），本地活体分静默活体、炫瞳活体、动作活体三种。
此处最终采集到的数据经过加密处理，需要配合开放平台人脸对比V4接口使用，包含活体检测、质量检测、人脸1:1识别功能，可通过传入参数进行控制，如您的业务场景核心为实名认证，无需重复请求7.3活体检测接口（startFaceLiveness）。

onCallback回调说明

resultMap key值列表说明：

常见问题

如何获取鸿蒙应用指纹

（1）方法1，测试证书

• “应用指纹”signatureInfo.fingerprint是鸿蒙应用签名证书(.cer文件)的SHA-256hash值，当前支持获取本应用的“应用指纹”。示例代码如下：
  

import { bundleManager } from '@kit.AbilityKit'; 
import { hilog } from '@kit.PerformanceAnalysisKit'; 
import { BusinessError } from '@kit.BasicServicesKit'; 
 
let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO; 
try { 
  bundleManager.getBundleInfoForSelf(bundleFlags).then((data) => { 
    hilog.info(0x0000, 'testTag', 'getBundleInfoForSelf successfully. Data: %{public}s', JSON.stringify(data)); 
    //data里可以获取到signatureInfo，即应用的签名证书信息 
  }).catch((err: BusinessError) => { 
    hilog.error(0x0000, 'testTag', 'getBundleInfoForSelf failed. Cause: %{public}s', err.message); 
  }); 
} catch (err) { 
  let message = (err as BusinessError).message; 
  hilog.error(0x0000, 'testTag', 'getBundleInfoForSelf failed: %{public}s', message); 
}

（2）方法2，测试证书+发布证书

• 在项目级build-profile.json5文件中，signingConfigs字段内的profile的值即为签名文件的存储路径。
• 打开该签名文件（后缀为.p7b），打开后在文件内搜索“development-certificate”，将“-----BEGIN CERTIFICATE-----”和“-----END CERTIFICATE-----”以及中间的信息拷贝到新的文本中，注意换行并去掉换行符，保存为一个新的.cer文件，如命名为xxx.cer。新的.cer文件格式如下图（仅作为格式示意，内容以实际为准）：
  
• 使用keytool工具（在DevEco Studio安装目录下的jbr/bin文件夹内），执行如下命令通过.cer文件获取证书指纹的SHA256值。
  keytool -printcert -file xxx.cer
• 将证书指纹中SHA256的内容去掉冒号，即为最终要获得的签名指纹。如SHA256值为下图（仅作为格式示意，内容以实际为准）：
  
  去掉冒号后的签名指纹为：5753DDBC1A8EF88A62058A9FC4B6AFAFC1C5D8D1A1B86FB3532739B625F8F3DB

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” 三项付费接口，是否有免费额度，或者直接开通后付费，以消除该报错提示。开通后，再进行重试。