尊敬的用户您好!即日起本官网将启用新域名"shanyan.253.com",原域名(flash.253.com)将自动跳转至新域名,原域名后期将停用。请您及时更新浏览器收藏夹或直接使用新域名访问本官网。万分感谢您的配合!

闪验、创蓝闪验

一.准备工作

概述

本文是人像比对SDK_Android v2.0.0版本的接入文档,用于指导SDK的使用方法,默认读者已经熟悉 IDE(Eclipse 或者 Android Studio)的基本使用方法,以及具有一定的 Android 编程知识基础。


前置条件

  • 人像比对SDK支持minSdkVersion 15及以上版本
  • cpu架构armeabi-v7a
  • 平台获取appId,appKey


快速体验demo


  • Android压缩包附带的apk文件夹中是人像比对demo的安装包,可以直接安装到Android手机上。并快速体验人像比对在您的手机上的表现。
  • Android压缩包附带的demo文件夹中是人像比对的示例工程,使用Android studio打开示例工程,完成以下步骤配置,然后直接运行起来测试。

a.将build里面的applicationId换成对应的测试包名

b.将签名配置改成您的签名配置

c.将AppId和AppKey换成您在人像比对平台创建应用后生成的信息


开发环境搭建


(1)将开发包拷贝到工程


将SDK中libs目录下的aar包拷贝到自己工程的libs目录下,如没有该目录需新建。


libs所在目录结构如下图

image.png



在app文件夹下的build.gradle的dependencies中配置对应版本的aar依赖并添加repositories,详细代码如下:

apply plugin: 'com.android.application'
android {
    compileSdkVersion xx
    defaultConfig {
        applicationId "xxx.xxx.xxx"
        minSdkVersion xx
        targetSdkVersion xx
        versionCode 1
        versionName "1.0.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

repositories {
    flatDir {
        dirs '../app/libs'
    }
}

dependencies {
    compile(name: 'cllc_sdk_1_1_0', ext: 'aar')
}


(2)配置AndroidManifest.xml文件


在manifest标签内添加必要的权限支持

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


配置权限说明

权限名称

权限说明

使用说明

CAMERA

允许访问相机权限

调用相机进行扫描或拍照

VIBRATE

允许程序振动

调用手机震动器再识别成功时发出震动

WRITE_EXTERNAL_STORAGE

允许程序写入外部存储,如SD卡上写文件

拍摄照片时的临时存储

INTERNET

允许应用程序联网

用于访问网关和认证服务器

ACCESS_NETWORK_STATE

允许程序获取网络信息状态

获取网络状态


(3) 混淆规则:

-keep class com.linkface.** { *; }


通过上面的几个步骤,工程就配置完成了,接下来就可以在工程中使用闪验SDK进行开发了。


二.SDK使用说明


1.初始化


使用人像比对前,必须先进行初始化操作。建议放在触发人像对比页面跳转前判断,回调在UI线程


方法原型

  public void init(Context context, 
                   String appId,
                   String appKey,
                   InitStateListener listener) {
  }


参数描述

参数

类型

说明

context

Context

必须传ApplicationContext对象

appId

String

人像比对平台获取到的appId

appKey

String

人像比对平台获取到的appKey

InitStateListener

listener

初始化回调监听,getInitStatu是该监听唯一的抽象方法,即void getInitStatus(int code, String result)


示例代码

 CLLCSDKManager.getInstance().init(getApplicationContext(),
                                  appid,appkey, 
                                  new InitStateListener() {
      @Override
      public void getInitStatus(int code, String msg) {
                
      }
});


getInitStatus(int code, String result)方法返回参数分为外层code和result,含义如下:

字段

类型

含义

code

Int

code为1000:成功;非1000:失败

result

String

返回信息

注意:初始化必须用户授权,否则将会失败,导致后续异常。


code错误码示例

code字段值

说明

1000

成功

1002

网络请求失败

1003

初始化数据解析异常

1004

后台错误(msg 对应后台错误提示)

1005

appId与appKey校验失败



2.设置检测参数


在初始化成功回调 进入检测页面 建议该方法放在活体检测Activity的onCreate() 方法中调用(必须放在主线程)。


方法原型

public void setCLLCParameter(final OcrParameter ocrParameter){}


参数描述

参数

成员参数

参数类型

说明

CLLCParameter

motionList

int[]

动作序列 最大长度4位 (0 请眨眨眼,1 请点点头,2 请张张嘴,3请瑶瑶头) 按数组顺序检测

outputType

String

检测返回的数据类型参数 (singleImg 单图,multiImg 多图,video 低质量视频)选其中之一

complexity

String

检测难度设置参数(四种难度,easy 容易,normal 正常,hard 困难,hell 究极)选其中之一

name

String

被检测人身份证名字

cardNo

String

被检测人身份证号码

isHack

boolean

是否添加hack检测(主要检测欺诈行为)


示例代码

CLLCParameter parameter = new CLLCParameter();
        //动作序列
        parameter.setMotionList(mDetectList);
        //输出类型
        parameter.setOutputType(“singleImg”);
        //难易程度
        parameter.setComplexity(“normal”);
        //姓名
        parameter.setName(“xxx”);
        //身份证号
        parameter.setCardNo("441xxxxxxxxxxxxxxx");
        //添加hack检测
        parameter.setHack(true);

//设置参数
CLLCSDKManager.getInstance().setCLLCParameter(parameter);



3.设置状态监听和认证结果监听


在设置参数完成后设置监听 


方法原型

 public void setLivenessListener(LivenessListener livenessListener,String url) {}


示例代码

CLLCSDKManager.getInstance().setLivenessListener(new LivenessListener() {
            @Override
            public void onLivenessDetect(int value, 
                                         int status,
                                         OcrImageResult[] imageResult) {
                

            @Override
            public void startVerify() {
            }

            @Override
            public void verifyResult(int code, String result) {
               
            }
                
            @Override
            public void detectTimeout() {
             
            }
                
            @Override
            public void detectInterrupt(int type) {
               
            }
                
            @Override
            public void onError(int code, String msg) {

            }
        },userUrl);



setLivenessListener回调方法说明

参数

类型

含义

livenessListener

LivenessListener

回调接口 

userUrl

String

用户设置自己的请求接口地址,默认传null(走创蓝接口,否则走用户设置接口  设置后 后台对接请参考人像综合评分接口文档)



LivenessListener回调方法说明

方法

回调环境

参数名

参数类型

含义

onLivenessDetect

UI线程

value

int

返回检测当前动作的 动作code (0 请眨眨眼,1 请点点头,2 请张张嘴,3请瑶瑶头)其他状态值 详见  SDK常量LivenessState类

status

int

返回当前动作的序号 例如当前是第一个动作 返回 0 第二个动作 返回1依次类推

imageResult

OcrImageResult[]

返回的图片数组数据


内部两个参数

byte[]类型的image

image 为图片的二进制数据

int类型length

length 为图片大小

startVerify

UI线程

开始调用比对身份和照片方法时调用

verifyResult

UI线程

code

int

1000为成功

其他code 参考下面(verifyResult回调 code字段说明)

result

String

code成功 result是json字符串 

code失败 result是错误信息

detectTimeout

UI线程

动作检测超时回调

detectInterrupt

UI线程

type

int

检测提示:

1,为请勿移出框外”。

2,为检测到多个人脸

 onError

UI线程

code

int

错误码:

1001(SDK校验失败)

-2(未知错误)

-1(SDK初始化失败)

1(未检测到人脸)

2(检测到多个人脸)

3(凑近一点)

4(请离远一点)

5(当前光线过强)

6(光线再亮一点)

13(请正对屏幕)

msg

String

对应错误码提示



verifyResult回调 code字段说明

code字段值

说明

1000

成功

1101

hack失败,网络请求失败(原因看verifyResult回调的另一个参数result字段提示)

1102

hack失败 ,服务器失败 (失败原因看verifyResult回调的另一个参数result字段提示)

1103

hack失败 ,数据解析失败 失败原因看verifyResult回调的另一个参数result字段提示)

1104

hack校验失败 (verifyResult回调的另一个参数result字段 result为json字符串 具体解析看“verifyResult回调 code为-1004   result结果的解析(result成功为json字符串)”

1105

综合评分失败,网络请求失败(原因看verifyResult回调的另一个参数result字段提示)



verifyResult回调 code为-1104    result结果的解析(result成功为json字符串

字段

类型

含义

score

float

hack评分  大于0,98为hack行为

request_id

String

本次请求的网络ID

image_id

String

本次请求后台记录的图片id

status

String

OK表示业务成功




verifyResult回调 code为1000  result结果的解析(result成功为json字符串

字段

类型

含义

code

int

状态码  code为200000 成功 ,非200000 看message信息

message

String

状态码描述

data

object

json字符串




data数据结构

字段

类型

含义

request_id

String

本次请求的id。

status

String

状态。正常OK,其他值表示失败。详见错误码

confidence

float

置信度。值为 0~1,值越大表示两张照片属于同一个人的可能性越大。无法得到近照时该值为null

selfie

object

请求参数中使用file、image_base64、url方式会返回图片的id。

identity

object

接口调用结果


identity数据结构

字段

类型

含义

validity

boolean

身份证和姓名经过接口验证是否匹配。匹配为true,不匹配为false

photo_id

String

近照ID。后台无该身份信息对应的近照时该值为null

reason

String

正常为Gongan status OK.其它值看reason字段详细描述


reason字段详细描述:

reason字段

含义

Gongan status OK

正常值

Gongan photo doesn’t exist

姓名和身份证号匹配,进照不存在

Name and idcard number doesn’t match

姓名与身份证号不匹配

Invalid idcard number

查无此身份证号

Gongan service timeout

接口获取超时

Gongan service is unavailable temporarily

服务不可用

Network error

网络错误

Unknown error

未知错误


置信度阈值与错误率对应关系:

阈值

0.4

0.5

0.6

0.7

0.8

0.9

错误率

十分之一

百分之一

千分之一

万分之一

十万分之一

百万分之一


data成功的json示例

{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "confidence": 0.312779,
  "selfie": { 
    "image_id": "xxxxx"
  },
  "identity": {
    "validity": true,
    "photo_id": "6963927a2b1e4fbc9abd9ff15638a2b5",
    "reason": "xxx"
  }
}


data失败的json示例

{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "INVALID_ARGUMENT",
  "reason": "Invalid idcard number"
}



status 错误码示例

status字段值

说明

PHOTO_SERVICE_ERROR

数据源服务服务出错,详见字段reason

ENCODING_ERROR

参数非UTF-8编码

IMAGE_ID_NOT_EXIST

图片不存在

IMAGE_FILE_SIZE_TOO_BIG

图片体积过大

NO_FACE_DETECTED

上传图片为检测出人脸

CORRUPT_IMAGE

文件不是图片文件或图片文件已损坏

INVALID_IMAGE_FORMAT_OR_SIZE

图片大小或格式不符合要求

INVALID_ARGUMENT

请求参数错误,详见字段reason

RATE_LIMIT_EXCEEDED

调用频率超出限额

OUT_OF_QUOTA

调用次数超出限额

NOT_FOUND

请求路径错误

INTERNAL_ERROR

服务器内部错误



4.添加图片数据监测


本方法主要添加图片二进制数据进行监测(在Camera.PreviewCallback的回调方法调用


方法原型

  public void setPicData(byte[] picData, Camera camera, int w, int h, int rotateAngle){}



参数类型

参数

类型

说明

picData

byte[]

预览图片数据

camera

Camera

预览Camera对象

w

int

图片宽度(需跟设置预览尺寸一致)

h

int

图片高度(需跟设置预览尺寸一致)

rotateAngle

int

图片旋转角度(需跟设置预览角度一致)


示例代码

  Camera.PreviewCallback mPreviewCallback = new Camera.PreviewCallback() {
        @Override
        public void onPreviewFrame(byte[] data, Camera camera) {
            CLLCSDKManager.getInstance().setPicData(data,
                                                   camera,
                                                   PREVIEW_WIDTH,
                                                   PREVIEW_HEIGHT,
                                                   mCameraInfo.orientation);
        }
    };




5.重置检测

本方法在SDK内部会创建内部检测类进行重新初始化(用于重置活体检测)


方法原型

  public void resetDetector(){}


示例代码

  CLLCSDKManager.getInstance().resetDetector();




6.释放资源

本方法在SDK内部关闭监测线程(建议在活体检测activity的onDestroy()执行)


方法原型

  public void remove(){}



示例代码

  CLLCSDKManager.getInstance().remove();




三.SDK常量说明

常量LivenessState类(监测活体返回常量判断)


成员

类型

说明

NONE

int

-1

空(无动作)

BLINK

int

0

请眨眨眼

NOD

int

1

请点点头

MOUTH

int

2

请张张嘴

YAW

int

3

请瑶瑶头

SUCCESS

int

4

成功

FAILED

int

5

采集失败,再试一次吧

TIME_OUT

int

6

超时

PREPARE

int

7

准备

START

int

8

开始

ERROR

int

-1000

SDK异常