Android SDK v1.1接口说明

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

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" />

LinkFace-release-1.1.jar(43 kB)

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

LinkFace.getInstance()

1. 初始化

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

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

参数说明：

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) {

参数说明：

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() {
    }
}

返回值：

示例代码：

    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)

参数说明：

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()

调用者需要实现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();