全部产品

Android SDK v1.1接口说明

LinkFace SDK封装了设备与云的通讯协议,实现了人脸信息增删查和人脸检测/识别事件上云等功能。SDK支持Android Studio开发环境。

SDK集成

LinkFace v1.1需要通过LinkKit SDK与服务端完成物模型相关通信,支持以下两种方式集成LinkKit SDK:

1) App独立集成LinkKit SDK能力,建议在LinkKit的onInitDone回调中进行LinkFace SDK初始化。

LinkFace同时会使用LinkKit创建的Http2通道进行文件传输,需要LinkKit初始化时支持Http2参数配置,完整示例如下:

    private void initLinkKit() {
        LinkKitInitParams params = new LinkKitInitParams();

        DeviceInfo deviceInfo = new DeviceInfo();
        deviceInfo.productKey = productKey;
        deviceInfo.deviceName = deviceName;
        deviceInfo.deviceSecret = deviceSecret;
        params.deviceInfo = deviceInfo;

        Map<String, ValueWrapper> propertyValues = new HashMap<>();
        params.propertyValues = propertyValues;

        IoTApiClientConfig userData = new IoTApiClientConfig();
        params.connectConfig = userData;

        IoTMqttClientConfig mqttClientConfig = new IoTMqttClientConfig(deviceInfo.productKey,
                deviceInfo.deviceName, deviceInfo.deviceSecret);
        mqttClientConfig.receiveOfflineMsg = true;
        mqttClientConfig.isCheckChannelRootCrt = true;
        params.mqttClientConfig = mqttClientConfig;

        // Http2通道配置
        IoTH2Config ioTH2Config = new IoTH2Config();
        ioTH2Config.clientId = "client-id";
        ioTH2Config.endPoint = "https://" + deviceInfo.productKey + ioTH2Config.endPoint;
        params.iotH2InitParams = ioTH2Config;
        Id2ItlsSdk.init(this);

        IoTDMConfig ioTDMConfig = new IoTDMConfig();
        ioTDMConfig.enableLocalCommunication = false;
        // 是否启用物模型功能,如果不开启,本地通信功能也不支持
        ioTDMConfig.enableThingModel = true;
        ioTDMConfig.enableGateway = false;
        ioTDMConfig.enableLogPush = false;
        params.ioTDMConfig = ioTDMConfig;

        LinkKit.getInstance().init(this, params, linkkitConnectListener);
    }

2) 注意:如果根据LinkKit demo由App自己实现对接,建议只处理除LinkFace外的明确的物模型服务调用,其他服务调用不要发送响应(demo代码默认会给所有服务调用发送空数据响应),否则可能导致LinkFace的服务响应无法被物联网平台收到,功能无法正常使用。

3) LinkFace SDK自动初始化LinkKit,通过设置init函数的needInitLinkKit参数为true实现。App如要处理自有物模型消息,则需要对接ILinkKitListener接口,参见接口说明部分。

依赖引入

本SDK以jar包形式提供,需要拷贝到项目的libs目录中,在build.gradle中添加相关引用。

// 在App build.gradle的dependencies中添加依赖
    implementation files('libs/LinkFace-release-1.1.jar')

混淆配置

-keep class com.aliyun.iotx.linkface.sdk.LinkFaceErrorCode { public *; }
-keep class com.aliyun.iotx.linkface.sdk.LinkFaceImageInfo { public *; }
-keep class com.aliyun.iotx.linkface.sdk.LinkFaceMatchResult { public *; }
-keep class com.aliyun.iotx.linkface.sdk.ILinkFaceCallback { *; }
-keep class com.aliyun.iotx.linkface.sdk.ILinkKitListener { *; }
-keep class com.aliyun.iotx.linkface.sdk.DeviceInfoEx { public *; }
-keep class com.aliyun.iotx.linkface.sdk.LinkFace { public *; }

-keep class com.aliyun.iotx.linkface.manager.FaceTsl { *; }
-keep class com.aliyun.iotx.linkface.manager.FaceDoorProperty { *; }
-keep class com.aliyun.iotx.linkface.manager.FaceGroupDTO { *; }
-keep class com.aliyun.iotx.linkface.manager.FaceGroupDTO$* { *; }

权限说明

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.INTERNET" />

SDK jar包

LinkFace-release-1.1.jar(43 kB)

接口说明

LinkFace通过单例方式进行接口调用,通过如下方式获取实例,再调用相关接口

LinkFace.getInstance()

1. 初始化

完成LinkKit接入和人脸信息管理准备工作。

void init(Context context, DeviceInfoEx deviceInfo, boolean needInitLinkKit, ILinkFaceCallback linkfaceCallback)

参数说明:

参数

类型

说明

context

Context

应用上下文,用于调用上下文环境相关的系统接口

deviceInfo

DeviceInfoEx

设备信息,用于LinkKit接入及初始属性上报,参见DeviceInfoEx定义

needInitLinkKit

boolean

指定SDK是否需要初始化LinkKit,若为false,则需要调用方提前完成LinkKit初始化,并在LinkKit的onInitDone回调中调用LinkFace的初始化接口。已接入LinkKit SDK的请直接设置为false。

linkfaceCallback

ILinkFaceCallback

LinkFace回调接口,需要调用方实现,并按要求完成相应人脸数据处理,参见LinkFace回调接口处理部分

DeviceInfoEx类定义:

public class DeviceInfoEx {
    // productKey、deviceName、deviceSecret为三元组必传信息
    public String productKey = null;
    public String deviceName = null;
   
    public String productSecret = null;
    public String deviceSecret = null;

    // 是否支持人脸特征、算法版本、固件版本必传信息
    public boolean supportFaceFeature = false;
    public String algorithmVersion = "";
    public String firewareVersion = "";

    public DeviceInfoEx() {
    }
}

示例代码:

    @Override
    public void onInitDone(Object o) {
        Log.d(TAG, "onInitDone");
        DeviceInfoEx deviceInfo = new DeviceInfoEx();
        deviceInfo.productKey = EnvConfig.CURRENT_DEV.productKey;
        deviceInfo.deviceName = EnvConfig.CURRENT_DEV.deviceName;
        deviceInfo.deviceSecret = EnvConfig.CURRENT_DEV.deviceSecret;
        deviceInfo.supportFaceFeature = true;
        deviceInfo.algoVersion = "1.0";
        deviceInfo.firewareVersion = "firmware-1.0";
        LinkFace.getInstance().init(this, deviceInfo, false,this);
    }

2. 上报人脸检测结果

无论人脸比对是否成功,均需要调用本接口上报检测结果,比对失败时,person id可以填空.

    /**
     * 当人脸门禁机检测到人脸后,无论是否能正确识别出该人脸,均需要调用本接口将识别结果上报到云端。
     *
     * @param matchResult 识别结果,如果识别成功,需要包含已识别的人的基本信息。
     * @return 成功返回0,失败返回-1
     * <p>
     * 注意:
     * 1. 该接口为同步接口,请勿并发调用。
     * 2. 上报结果需要一定耗时,建议不要在UI线程中调用本接口。
     * 3. 若接口返回失败,建议最多重试3次。
     */
    public int uploadMatchResult(LinkFaceMatchResult matchResult) {

参数说明:

参数

类型

说明

matchResult

LinkFaceMatchResult

人脸比对结果,参见LinkFaceMatchResult定义

LinkFaceMatchResult定义:

public class LinkFaceMatchResult {

    /**
     * 比对失败
     */
    public static final int LINKFACE_MATCH_STATUS_FAILED = -1;

    /**
     * 未进行比对
     */
    public static final int LINKFACE_MATCH_STATUS_NULL = 0;

    /**
     * 比对成功
     */
    public static final int LINKFACE_MATCH_STATUS_SUCCESS = 1;

    /**
     * 比对状态<br>
     * 对比成功才会有人脸(即person_id, match_score)的值才有意义
     */
    public int linkFaceMatchStatus;

    /**
     * 人脸比对到的人员ID, 抓拍成功时, 必要字段<br>
     * 长度不超过32个字符
     */
    public String personId;

    /**
     * 对比相似度, 抓拍成功时,必要字段, 范围为[1, 100]
     */
    public int matchScore;

    /**
     * 人脸全景图原始数据<br>
     * 不能超过10MByte<br>
     * 大小大于0时全景图的数据才有意义,否则全景图所有数据全部置空
     */
    public byte[] panoramaImgRawData;

    /**
     * 人脸全景图名称
     */
    public String panoramaImgName;

    /**
     * 比对事件发生时的时间戳, 单位ms
     */
    public long timestampMs;

    public LinkFaceMatchResult() {
    }
}

返回值:

类型

说明

int

成功返回0,失败返回-1。该接口为同步接口,请勿并发调用,失败时建议最多重试3次。

示例代码:

    public void uploadMatchResultClicked(View view) {
        LinkFaceMatchResult linkFaceMatchResult = new LinkFaceMatchResult();
        linkFaceMatchResult.linkFaceMatchStatus = LinkFaceMatchResult.LINKFACE_MATCH_STATUS_SUCCESS;
        linkFaceMatchResult.personId = "007";
        linkFaceMatchResult.panoramaImgRawData = mockFacePictureData;
        linkFaceMatchResult.timestampMs = System.currentTimeMillis();
        linkFaceMatchResult.panoramaImgName = System.currentTimeMillis() + "_taylor-swift.png";
        linkFaceMatchResult.matchScore = 78;
        int ret = LinkFace.getInstance().uploadMatchResult(linkFaceMatchResult);
        appendLog("上报人脸比对结果 ret="+ret);
    }

3. 注册/注销LinkKit监听者回调

若由LinkFace完成LinkKit初始化,调用方仍希望处理自有物模型属性或者服务调用,可注册监听者回调进行处理。已接入LinkKit SDK的无需关注。

void registerLinkKitListener(ILinkKitListener linkkitListener)
void unregisterLinkKitListener(ILinkKitListener linkkitListener)

参数说明:

参数

类型

说明

linkkitListener

ILinkKitListener

LinkKit监听者回调,参见ILinkKitListener定义

ILinkKitListener定义:

public interface ILinkKitListener {
    public static final int LKS_INIT_ERROR = -1;
    public static final int LKS_CONNECT_OFFLINE = 0;
    public static final int LKS_CONNECT_ONLINE = 1;

    void onInitDone();
    void onStatusChange(int status, Object data);

    void onSetProperty(JSONObject properties);

    // 执行完需要发送响应消息,可以调用LinkFace.getInstance().sendServiceResponse(int code, JSONObject data)
    void onInvokeService(String serviceId, String serviceIdentifier, JSONObject params);

    void onBroadcast(String identifier, JSONObject data);
}

4. 释放资源

退出时调用释放LinkFace使用的资源。

void destroy()

LinkFace回调接口处理

调用者需要实现ILinkFaceCallback接口来完成人脸相关操作处理

1.SDK初始化结果异步通知

    /**
     * SDK初始化结果
     * @param code
     */
    void onInit(int code);

2.添加人脸底库

    /**
     * 云端下发底库同步请求时,sdk先缓存人脸图片,再调用该接口将图片入库。
     *
     * @param imageInfo 注册人脸图片信息
     * @return 图片入库结果. 参考:{@link com.aliyun.iotx.linkface.sdk.LinkFaceErrorCode}
     * <p>
     * 注意:<br>
     * 1. 该接口为同步调用,接口不宜耗时过久<br>
     * 2. 该接口不会在多线程中并发调用<br>
     * 3. 错误码请严格按照 {@link com.aliyun.iotx.linkface.sdk.LinkFaceErrorCode} 中的定义<br>
     */
    int onAddImageInfo(LinkFaceImageInfo imageInfo);

3.删除人脸底库

    /**
     * 云端需要删除某个人脸底库时,sdk会调用该接口将人脸信息逐个传递给厂商,厂商需要将该人脸从数据库中删除
     * @param   imageInfo 待删除图片信息
     * @ret     如果删除人脸成功,则返回0,否者返回其他值. 参考:{@link com.aliyun.iotx.linkface.sdk.LinkFaceErrorCode}
     *
     * 注意:<br>
     * 1. 只有人脸数据真实存在时(personId/faceImageMd5),才返回成功。<br>
     * 2. personId 不存在返回-1。<br>
     * 3. personId 存在而 faceImageMd5 不存在,返回-2。<br>
     */
    int onDeleteImageInfo(LinkFaceImageInfo imageInfo);

4.查询人脸底库总数

    /**
     * 查询端侧人脸底库总数
     *
     * @return 人脸底库总数
     */
    int onQueryImageCount();

5.清空所有人脸底库记录

    /**
     * 将算法特征库的内容完全清空并删除数据库记录
     * @return 如果清空成功,则返回0,否者返回具体错误码. 参考:{@link com.aliyun.iotx.linkface.sdk.LinkFaceErrorCode}
     */
    int onClearAll();