Android-方案集成指南(升级)

前言

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

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

快速定位

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

1. 文档说明

2. 版本说明

3. SDK说明

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

4. 配置包名和签名

从百度云控制台下载Demo之后，需要在build.gradle中配置好包名和签名信息。

5. SDK集成与授权

• 首先在app工程中增加3. SDK说明中的依赖库资源
  

  Notice: 如果需要使用OCR身份证识别能力，则需要增加此ocr-ui-release.aar，如果不使用则不需要增加。在app工程的build.gradle中添加相关依赖，然后点击运行。

• 其次将百度云控制台创建应用时获取的人脸授权文件(idl-license.face-android)放置于Assets目录下。//如果集成物料下载渠道为控制台，可忽略
  

  如果使用OCR身份证识别功能，请将OCR身份证识别授权文件（aip.license）也放置于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个方法：
(1) setFaceQualityConfig()：人脸质量判断相关配置
(2) setFaceLivenessConfig()：设置活体类型、活体动作

// 是否开启炫彩活体能力
faceLiveConfig.setIsOpenColorLive(true);
// 是否开启动作活体能力
faceLiveConfig.setIsOpenActionLive(true);
livenessValueModel = faceLiveConfig.getLivenessValueModel();
// 设置动作池
livenessValueModel.actionList.addAll(consoleConfig.getActions());
// 设置动作随机数
livenessValueModel.actionRandomNumber = consoleConfig.getFaceActionNum();

注：不设置，将使用默认值。

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

14.1 OCR身份证识别-初始化接口

入参说明

onError回调参数说明：

14.2 OCR身份证识别-识别接口

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

入参说明

OcrConfig配置字段说明

onError回调参数说明

代码混淆

-dontwarn com.baidu.idl.**
-keep class com.baidu.idl.** { *; }
-dontwarn com.baidu.vis.**
-keep class com.baidu.vis.** { *; }
-dontwarn com.baidu.liantian.**
-keep class com.baidu.liantian.** { *; }
-dontwarn com.baidu.protect.**
-keep class com.baidu.protect.** { *; }
-dontwarn com.baidu.ocr.**
-keep class com.baidu.ocr.** { *; }

权限

不使用OCR，只使用人脸相关能力

不使用OCR，可以删除ocr-ui.aar、aip.license，以及OCR相关代码。 OCR初始化代码如下图所示：

OCR调用代码如下图所示：

设置页面，关闭OCR运行Demo即可。

常见问题

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