人脸识别 JavaScriptApi

概述

人脸识别相关接口，JavaScript 对应对象为 window.FaceRecognition

人脸特征码

通过算法从图片中提取到的特征码数据，同一个图片提取出来的特征码不保证完全一致。目前使用的模型提取到的特征码长度为256字节。该数据是人脸识别的基础数据。

人脸ID

人脸特征码对应的唯一值，除了插入人脸特征码需要用到人脸特征码外，其他相关接口使用的都是该数据，文档中说的 faceId 和 token 都是这个概念。

人脸识别设备授权

void authDevice(String cert, String password, SimpleCallBack callBack)

目前人脸识别使用的是旷视的人脸识别算法，需要授权才能使用，授权成功后才能使用人脸识别功能。每次启动应用需要调用一次查询设备授权状态接口判断授权状态，如果没授权需要调用此接口进行授权。

参数

Param	Description
cert	授权信息
password	授权密码
callBack	回调

调用示例
window.FaceRecognition.authDevice("cert", "password", function (result) {
    var data = JSON.parse(result);
    if (data.code === 0) {
        console.log("authDevice success");
    } else {
        console.log("authDevice fail");
    }
});

查询设备授权状态

boolean isAuthorized()

查询设备授权状态

返回值

是否授权成功

调用示例
window.FaceRecognition.isAuthorized();

初始化

void initSDK(SimpleCallBack callBack)

初始化人脸识别，需要判断授权结果后再调用

参数

Param	Description
callBack	回调

调用示例
window.FaceRecognition.initSDK(function (result) {
    var data = JSON.parse(result);
    if (data.code === 0) {
        console.log("initSDK success");
    } else {
        console.log("initSDK fail");
    }
});

图片生成人脸特征码

void base64Image2FaceFeature(String base64, SimpleCallBack callBack)

base64图片生成特征码

参数

Param	Description
base64	base64图片数据
callBack	回调

调用示例
window.FaceRecognition.base64Image2FaceFeature(feature, function (result) {
    // code值为0标识生成成功，data字段为特征码数据，格式是十六进制字符串
    // code值非0表示调用失败， 1-没有检测到人脸 2-检测到人脸，但是没有通过质量判断 3-base64解码失败 4-生成特征码接口错误 5-正在生成特征码，接口不可用
    var data = JSON.parse(result);
    console.log(data.code)
});

插入人脸特征码

boolean insertFeature(String feature, String token)

插入人脸特征码，用于后续人脸识别。需要注意：

token 需要保证唯一，如果插入的 token 已经存在，会覆盖原有的特征码。
token 的长度必须超过 26 位字符串，如果业务中使用的 token 长度不够，可以调用设置人脸唯一值前缀来解决该问题。
特征码必须是 256 字节、512 字节、2048 字节其中一个，如果传入的特征码长度不够，会导致插入失败。

参数

Param	Description
feature	人脸特征码
token	人脸唯一值，用于业务

调用示例
window.FaceRecognition.insertFeature(feature, token);

批量插入人脸特征码

void insertFeatures(String jsonData)

批量插入人脸特征码，用于后续人脸识别

参数

Param	Description
jsonData	人脸特征码 json 数据

调用示例
// jsonData 格式: [{"data":"AABB","token":"CCDD"}] data 为人脸特征码，token 为人脸唯一值
window.FaceRecognition.insertFeatures(jsonData);

批量异步插入人脸特征码

void insertFeaturesAsync(String jsonData, SimpleCallBack callBack)

批量异步插入人脸特征码，用于后续人脸识别，调用接口后直到回调完成期间，不可调用其他任何人脸识别相关接口

参数

Param	Description
jsonData	人脸特征码 json 数据
callBack	回调

调用示例
// jsonData 格式: [{"data":"AABB","token":"CCDD"}] data 为人脸特征码，token 为人脸唯一值
window.FaceRecognition.insertFeaturesAsync(jsonData, function (result) {
    // 插入成功和失败的人脸ID数组，数据格式为 JSON 字符串，如：`{code: 0, data: '{"success":["token1","token2"],"fail":["token3","token4"]}'}`
    // code值非0表示调用失败，失败情况下data字段为空
    var data = JSON.parse(result);
    console.log(data.code)
    console.log(JSON.parse(data.data).success);
    console.log(JSON.parse(data.data).fail);
});

设置人脸唯一值前缀

void setFaceIdPrefix(String faceIdPrefix)

该接口是为了解决调用方传入 token 不够 26 位问题。比如设置为 ShineFaceRecognitionPrefix，如果调用插入人脸特征码传入的参数为 123456，则人脸底库中 token 为 ShineFaceRecognitionPrefix123456，但是不会影响到识别成功后回调给调用方的 token，回调后的 token 仍然是 123456。

参数

Param	Description
faceIdPrefix	token 前缀

调用示例
window.FaceRecognition.setFaceIdPrefix("ShineFaceRecognitionPrefix");

删除人脸特征码

boolean deleteFeature(String token)

删除人脸特征码

参数

Param	Description
token	人脸唯一值，用于业务

返回值

是否删除特征码成功

调用示例
const result = window.FaceRecognition.deleteFeature(token);

批量删除人脸特征码

void deleteFeatures(String[] tokens, SimpleCallBack callBack)

通过人脸ID批量删除人脸特征码

参数

Param	Description
tokens	人脸ID数组，用于业务
callBack	回调

调用示例
window.FaceRecognition.deleteFeatures(["ID1","ID2","ID3"], function (result) {
    // 插入成功和失败的人脸ID数组，数据格式为 JSON 字符串，如：`{code: 0, data: '{"success":["token1","token2"],"fail":["token3","token4"]}'}`
    // code值非0表示调用失败，失败情况下data字段为空
    var data = JSON.parse(result);
    console.log(data.code)
    console.log(JSON.parse(data.data).success);
    console.log(JSON.parse(data.data).fail);
});

创建人脸底库组

boolean createLocalGroup(String groupName)

人脸识别基于人脸组进行识别，默认创建一个名为 shine 的组。如果需要创建其他组，可以调用此接口，业务方可以根据需要创建多个组，每个组可以存储不同个人脸特征码

参数

Param	Description
groupName	人脸底库组

返回值

是否创建成功

调用示例
window.FaceRecognition.createLocalGroup("business");

获取所有人脸底库组

String[] getLocalGroups()

获取所有人脸底库组

返回值

人脸底库名称数组

调用示例
window.FaceRecognition.getLocalGroups();

查询底库的详细信息

String[] getLocalGroupInfo(String group)

获取对应人脸底库组的所有token

返回值

token数组

调用示例
window.FaceRecognition.getLocalGroupInfo(String group);

绑定人脸唯一值到组

boolean bindGroup(String groupName, String token)

绑定人脸唯一值到指定组，支持一个人脸绑定多个组

参数

Param	Description
groupName	人脸组
token	人脸唯一值，用于业务

返回值

是否绑定成功

调用示例
// 绑定到名称为 shine 的组
window.FaceRecognition.bindGroup("shine", tokens);

批量绑定人脸唯一值到组

boolean bindGroups(String groupName, String[] tokens)

批量绑定人脸唯一值到指定组

参数

Param	Description
groupName	人脸组
tokens	人脸唯一值数组

调用示例
// 绑定到名称为 shine 的组
window.FaceRecognition.bindGroups("shine", tokens);

批量异步绑定人脸唯一值到组

boolean bindGroupsAsync(String groupName, String[] tokens, SimpleCallBack callBack)

批量异步绑定人脸唯一值到指定组，调用接口后直到回调完成期间，不可调用其他任何人脸识别相关接口

参数

Param	Description
groupName	人脸组
tokens	人脸唯一值数组
callBack	回调

调用示例
// 绑定到名称为 shine 的组
window.FaceRecognition.bindGroupsAsync("shine", ["token1","token2","token3","token4"], function (result) {
    // 成功和失败的人脸ID数组，数据格式为 JSON 字符串，如：`{code: 0, data: '{"success":["token1","token2"],"fail":["token3","token4"]}'}`
    // code值非0表示调用失败，失败情况下data字段为空
    var data = JSON.parse(result);
    console.log(data.code)
    console.log(JSON.parse(data.data).success);
    console.log(JSON.parse(data.data).fail);
});

初始化人脸底库组

boolean initLocalGroup(String groupName)

初始化加载底库里的人脸信息到内存中，用户可以加载多个 groupName。如果不提前加载人脸信息到内存，第一次识别时，会触发加载底库里人脸信息，导致第一次识别偏慢，甚至有可能超时识别。因此，提前将人脸信息加载到内存，可以提升第一次识别的耗时。

参数

Param	Description
groupName	人脸组

返回值

是否初始化成功

调用示例
// 绑定到名称为 shine 的组
window.FaceRecognition.initLocalGroup("shine");

删除人脸底库组

boolean deleteLocalGroup(String groupName)

删除人脸底库组

参数

Param	Description
groupName	人脸底库组

返回值

是否删除成功

调用示例
window.FaceRecognition.deleteLocalGroup("business");

清空所有人脸数据

boolean clearAllGroupsAndFaces()

清空所有人脸底库数据

返回值

是否清空成功

调用示例
window.FaceRecognition.clearAllGroupsAndFaces();

设置预览画面角度

void setCameraRotation(int cameraRotation)

设置预览画面角度，参数只能传入 0、90、180、270。旋转方向为顺时针方向。和相机 Api 中设置预览画面角度共享同一个变量，设置后两边都会生效。

参数

Param	Description
cameraRotation	预览角度

调用示例
window.CameraView.setCameraRotation(90);

设置算法图形角度

void setImageAlgorithm(int rotation)

设置算法图形角度，参数只能传入 0、90、180、270。旋转方向为顺时针方向。由于预览角度和传入人脸识别算法的图形角度不一致，所以在调整好预览角度以后还需要设置该参数，保证人脸识别算法能够正常识别。

参数

Param	Description
rotation	算法角度

调用示例
window.CameraView.setImageAlgorithm(90);

开始人脸识别

void startFaceRecognition(int x, int y, int width, int height, String groupName, SimpleCallBack callBack)

开始人脸识别，根据参数生成一个预览画面显示在屏幕上

caution

调用该接口后，除调用停止人脸识别外，不要再调用人脸识别其他接口

人脸识别框说明

如果开始人脸识别后没有人脸识别框，调整后台算法图形角度参数，或者通过设置算法图形角度调整角度。人脸识别框根据颜色分为四种状态：

白色：人脸识别数据异常，检查是否插入了人脸特征码，或者人脸底库组参数是否正确。也可以通过查看 /sdcard/shine/facepass.db 文件判断数据是否正常。
黄色：人脸识别中，等待识别结果。
绿色：人脸识别成功。
红色：人脸识别失败。

参数

Param	Description
x	预览框 x 轴位置
y	预览框 y 轴位置
width	预览框宽度
height	预览框高度
groupName	人脸底库组
callBack	回调

调用示例
window.FaceRecognition.startFaceRecognition(0, 0, 300, 300, "shine", function (result) {
    var data = JSON.parse(result);
    // 回调数据结构：[{"trackId":5, "state":0, "token":"s_383838339", "searchScore":80.45,"livenessScore":92.678}]
    // trackId: 人脸轨迹 id
    // state: 人脸状态，0 为识别成功，1 为再次尝试识别中，2 为识别失败，3 为识别进行中
    // token: 人脸唯一值，对应的是插入特征码时传入的 token
    // searchScore: 识别分数，范围 0-100，越大越好
    // livenessScore: 活体分数，范围 0-100，越大越好
    console.log(data);
});

开始人脸识别（支持控制识别框参数）

void startFaceRecognitionShowBox(int x, int y, int width, int height, String groupName, boolean isShowBox, SimpleCallBack callBack)

开始人脸识别，添加是否显示人脸识别框参数

参数

Param	Description
x	预览框 x 轴位置
y	预览框 y 轴位置
width	预览框宽度
height	预览框高度
groupName	人脸底库组
isShowBox	是否显示人脸识别框
callBack	回调

调用示例
window.FaceRecognition.startFaceRecognitionShowBox(0, 0, 300, 300, "shine", false, function (result) {
    var data = JSON.parse(result);
    // 回调数据结构：[{"trackId":5, "state":0, "token":"s_383838339", "searchScore":80.45,"livenessScore":92.678}]
    // trackId: 人脸轨迹 id
    // state: 人脸状态，0 为识别成功，1 为再次尝试识别中，2 为识别失败，3 为识别进行中
    // token: 人脸唯一值，对应的是插入特征码时传入的 token
    // searchScore: 识别分数，范围 0-100，越大越好
    // livenessScore: 活体分数，范围 0-100，越大越好
    console.log(data);
});

停止人脸识别

void stopFaceRecognition()

停止人脸识别

调用示例
window.FaceRecognition.stopFaceRecognition();

开始人证比对

void startCompareFaceWithImage(int x, int y, int width, int height, String base64, SimpleCallBack callBack)

人证比对

参数

Param	Description
x	预览框 x 轴位置
y	预览框 y 轴位置
width	预览框宽度
height	预览框高度
base64	图片 base64 数据, 可为空
callBack	回调

调用示例
window.FaceRecognition.startCompareFaceWithImage(0, 0, 300, 300, "image base64 data", function (result) {
    var data = JSON.parse(result);
    // 回调数据结构：[{"trackId":5, "state":0, "token":"s_383838339", "searchScore":80.45,"livenessScore":92.678}]
    // trackId: 人脸轨迹 id
    // state: 人脸状态，0 为识别成功，1 为再次尝试识别中，2 为识别失败，3 为识别进行中
    // searchScore: 识别分数，范围 0-100，越大越好
    // livenessScore: 活体分数，范围 0-100，越大越好
    console.log(data);
});

停止人证比对

void stopCompareFaceWithImage()

停止人证比对

调用示例
window.FaceRecognition.stopCompareFaceWithImage();

设置人证比对 base64 格式图片数据

void setCompareFaceBase64Image(String base64)

设置用于人证比对的 base64 格式图片数据

调用示例
window.FaceRecognition.setCompareFaceBase64Image("image base64 data");

采集人脸特征码

void startCaptureFaceFeature(int x, int y, int width, int height, SimpleCallBack callBack)

采集人脸特征码，采集后自动关闭预览画面

参数

Param	Description
x	预览框 x 轴位置
y	预览框 y 轴位置
width	预览框宽度
height	预览框高度
callBack	回调

调用示例
window.FaceRecognition.startCaptureFaceFeature(0, 0, 300, 300, function (result) {
    var data = JSON.parse(result);
    // 回调数据结构：{"code": 0, "data": {"faceFeature": "AABB", "imagePath": "/sdcard/shine/captureface.jpg"}}
    // faceFeature: 16进制字符串，人脸特征码
    // imagePath: 人脸图片路径
    console.log(data);
});

采集人脸特征码（不自动关闭预览画面）

void startFaceCaptureWithoutAutoStop(int x, int y, int width, int height, SimpleCallBack callBack)

持续采集人脸特征码，不自动关闭预览画面

参数

Param	Description
x	预览框 x 轴位置
y	预览框 y 轴位置
width	预览框宽度
height	预览框高度
callBack	回调

调用示例
window.FaceRecognition.startFaceCaptureWithoutAutoStop(0, 0, 300, 300, function (result) {
    var data = JSON.parse(result);
    // 回调数据结构：{"code": 0, "data": {"faceFeature": "AABB", "imagePath": "/sdcard/shine/captureface.jpg"}}
    // faceFeature: 16进制字符串，人脸特征码
    // imagePath: 人脸图片路径
    console.log(data);
});

停止采集人脸特征码

void stopCaptureFaceFeature()

停止采集人脸特征码

调用示例
window.FaceRecognition.stopCaptureFaceFeature();

获取人脸识别处理程序状态

int getFaceRecognitionHandlerState()

获取人脸识别处理程序状态时，可以根据以下条件进行判断，并避免频繁开启关闭摄像头导致程序异常：

闲置状态：检查是否处于闲置状态，即没有正在进行人脸识别或其他相关操作。该状态可以调用开始人脸识别接口。
开启中：检查是否正在开启人脸识别处理程序。该状态不可以调用其他人脸识别相关接口。
开启完成：检查是否开启完成人脸识别处理程序。只有该状态可以调用停止人脸识别接口。

返回值

0：闲置 1：开启中 2：开启完成

调用示例
window.FaceRecognition.getFaceRecognitionHandlerState();

人脸识别 JavaScriptApi

概述​

人脸识别设备授权​

参数​

查询设备授权状态​

返回值​

初始化​

参数​

图片生成人脸特征码​

参数​

插入人脸特征码​

参数​

批量插入人脸特征码​

参数​

批量异步插入人脸特征码​

参数​

设置人脸唯一值前缀​

参数​

删除人脸特征码​

参数​

返回值​

批量删除人脸特征码​

参数​

创建人脸底库组​

参数​

返回值​

获取所有人脸底库组​

返回值​

查询底库的详细信息​

返回值​

绑定人脸唯一值到组​

参数​

返回值​

批量绑定人脸唯一值到组​

参数​

批量异步绑定人脸唯一值到组​

参数​

初始化人脸底库组​

参数​

返回值​

删除人脸底库组​

参数​

返回值​

清空所有人脸数据​

返回值​

设置预览画面角度​

参数​

设置算法图形角度​

参数​

开始人脸识别​

参数​

开始人脸识别（支持控制识别框参数）​

参数​

停止人脸识别​

开始人证比对​

参数​

停止人证比对​

设置人证比对 base64 格式图片数据​

采集人脸特征码​

参数​

采集人脸特征码（不自动关闭预览画面）​

参数​

停止采集人脸特征码​

获取人脸识别处理程序状态​

返回值​

概述

人脸识别设备授权

参数

查询设备授权状态

返回值

初始化

参数

图片生成人脸特征码

参数

插入人脸特征码

参数

批量插入人脸特征码

参数

批量异步插入人脸特征码

参数

设置人脸唯一值前缀

参数

删除人脸特征码

参数

返回值

批量删除人脸特征码

参数

创建人脸底库组

参数

返回值

获取所有人脸底库组

返回值

查询底库的详细信息

返回值

绑定人脸唯一值到组

参数

返回值

批量绑定人脸唯一值到组

参数

批量异步绑定人脸唯一值到组

参数

初始化人脸底库组

参数

返回值

删除人脸底库组

参数

返回值

清空所有人脸数据

返回值

设置预览画面角度

参数

设置算法图形角度

参数

开始人脸识别

参数

开始人脸识别（支持控制识别框参数）

参数

停止人脸识别

开始人证比对

参数

停止人证比对

设置人证比对 base64 格式图片数据

采集人脸特征码

参数

采集人脸特征码（不自动关闭预览画面）

参数

停止采集人脸特征码

获取人脸识别处理程序状态

返回值