芝麻认证接入文档

1、MegviiCloudFace+芝麻认证 SDKZMCertificationv1.0.3变更和修订历史记录文档编号：版本号完成日期修改记录1.0.02016-12-23初稿1.0.12017-2-26增加用户每日调用次数达到上限的错误类型；增加FAQ1.0.22017-3-31算法升级1.0.32017-5-2增加视频录制方法目录芝麻认证 SDK1ZMCertification1v1.0.31目录21芝麻认证简介31.1芝麻认证SDK31.2芝麻认证逻辑32SDK接口32.1Android接口32.1.1类ZMCertification32.1.2ZMCertification.getIns

2、tance32.1.3ZMCertification.getVersion32.1.4ZMCertification.setZMCertificationListener42.1.5ZMCertification.setZMRecordVideoListener42.1.6ZMCertification.startCertification42.1.7ZMCertification的ErrorCode52.1.8接口ZMCertificationListener52.1.9接口ZMRecordVideoListener62.2iOS接口62.2.1类ZMCertification62.2.2Z

3、MCertification.startCertification62.2.3ZMCertification.getVersion72.2.4ZMCertification的回调函数72.2.5枚举ZMStatusErrorType83SDK集成93.1Android集成93.1.1Android Studio（aar）93.1.2Eclipse（Project Library）103.2iOS集成103.2.1将 ZMCert.framework 文件添加进入项目103.2.2引入所需的系统库113.2.3环境配置113.2.4引入 .bundle 资源文件113.2.5引入头文件113.2

4、.6一份简单的示例代码114FAQ114.1SDK使用需要那些设备权限？114.2SDK 支持哪些手机，支持什么操作系统，对设备有什么要求？124.3Android SDK一直不释放我的listener导致有内存泄露怎么办？124.4Android程序只需要使用armv7a的so库，不需要使用arm64的so库124.5Android程序有一些特殊的布局需求124.6视频录制功能有什么使用条件限制131 芝麻认证简介1.1 芝麻认证SDK芝麻认证SDK是由蚂蚁金服及Face+|旷视公司一同开发的，基于生物特征的身份验证SDK。芝麻认证SDK 对接方便，易于集成，使用简单，同时支持Android

5、和iOS双平台，服务于大中小各类互联网企业。1.2 芝麻认证逻辑芝麻认证逻辑大致分为三步：1. 调用芝麻验证WebAPI，获取bizNO（业务串号） 以及 merchantID（商户号）；2. 使用bizNO 和merchantID 完成SDK初始化，进入认证页面；3. 用户通过认证流程后，返回商户界面，并通过回调告知结果。2 SDK接口2.1 Android接口2.1.1 类ZMCertificationZMCertification类是管理芝麻认证的类，此类不可以初始化，只能通过getInstance获得其单例。2.1.2 ZMCertification.getInstance函数名get

6、InstanceZMCertification getInstance()名称获取ZMCertification的实例类型说明函数说明获取ZMCertification的单例。返回值ZMCertification一个实例2.1.3 ZMCertification.getVersion函数名CreateApiHandleString getVersion()名称获取SDK的版本号类型说明函数说明无返回值String一个字符串，表示当前SDK的版本号。如：ZMCert 1.0.0A2.1.4 ZMCertification.setZMCertificationListener函数名setZMCer

7、tificationListenervoid setZMCertificationListener(ZMCertificationListener listener)名称注册回调监听者类型说明函数说明监听者会在芝麻验证结束后被调用，如果没有设置，则不会调用。变量名说明类型listener监听者ZMCertificationListener2.1.5 ZMCertification.setZMRecordVideoListener函数名setZMRecordVideoListenervoid setZMRecordVideoListener(ZMRecordVideoListener liste

8、ner)名称注册视频录制回调监听者类型说明函数说明监听者会在芝麻验证结束后被调用，如果没有设置，则不会调用。如果初始化时没有要求录制视频，也不会回调。变量名说明类型listener监听者ZMRecordVideoListener2.1.6 ZMCertification.startCertification函数名startCertificationvoid startCertification(Activity activity, String bizNO, String merchantID, HashMap extParams)名称开始认证类型说明函数说明传入bizNO和merchantI

9、D开始芝麻验证。接口通过bizNO和 merchantID 初始化 SDK 接口，完成验证流程后回跳回原来的 Activity。验证的结果会通过注册的 listener进行回调。变量名说明类型activity当前页面所在的ActivityActivitybizNO业务串号，通过芝麻认证WebAPI获得StringmerchantID商户号StringextParams额外的传入参数，目前传入null即可如果需要录制视频，则传入：RecordVideo = TrueHashMap2.1.7 ZMCertification的ErrorCode名称说明数值none无0verification_fai

10、led用户人脸与数据库中的人脸比对分数较低1device_not_support手机在不支持列表里2no_permission缺少手机权限3no_network_permission没有联网权限4no_camera_permission没有打开相机的权限5no_sensor_permission无法读取运动数据的权限6face_init_fail人脸采集算法初始化失败7network_error发生网络错误8invalid_biz_no传入的bizNO 有误9invalid_bundle_id此APP的bundle_id在系统的黑名单库里10data_source_error数据源错误11in

11、ternal_error服务发生内部错误12unmatched_merchant_idbizNO和merchantID不匹配13version_too_oldSDK版本过旧14userinfo_error身份证号和姓名的格式不正确15bizno_limit_exceed身份证号和姓名在一天内使用次数过多16wrong_system_time用户当前的设备时间与授权时间不符17no_write_external_storage_permission没有写存储空间的权限182.1.8 接口ZMCertificationListenerZMCertificationListener是一个回调接口，当

12、完成芝麻认证逻辑后，会调用此接口。ZMCertificationListener.onFinish函数名onFinishvoid onFinish(boolean isCanceled, boolean isPassed, int errorCode)名称完成芝麻认证后回调类型说明函数说明无变量名说明类型isCanceled是否取消了芝麻认证，如果是则isPassed和errorCode的返回值均无意义。booleanisPassed是否通过了芝麻认证，如果没有通过则返回errorCode表示失败的原因。booleanerrorCode没有通过芝麻认证的原因，具体参见文档中的ErrorCode

13、说明int2.1.9 接口ZMRecordVideoListenerZMRecordVideoListener是一个回调接口，当完成芝麻认证逻辑后，会调用此接口。ZMRecordVideoListener.onRecordVideoFinish函数名onRecordVideoFinishvoid onRecordVideoFinish(String videoPath)名称完成芝麻认证后回调，返回录制视频的地址若类型说明函数说明无变量名说明类型videoPath地址默认都在app的默认存储空间内，如果返回的结果为 null，则表示视频录制失败。String2.2 iOS接口2.2.1 类ZMC

14、ertificationZMCertification类是管理芝麻认证的类，此类使用默认的构造函数初始化即可。2.2.2 ZMCertification.startCertification函数名startCertification- (void)startWithBizNO:(NSString *_nonnull)bizNO merchantID:(NSString *_nonnull)merchantID extParams:(NSDictionary *_nullable)params viewController:(UIViewController *_nonnull)vc onFin

15、ish:(void(_nullable)(BOOL isCanceled, BOOL isPassed, ZMStatusErrorType errorCode)callback;- (void)startVideoWithBizNO:(NSString *_nonnull)bizNO merchantID:(NSString *_nonnull)merchantID extParams:(NSDictionary *_nullable)params viewController:(UIViewController *_nonnull)vc onFinish:(void(_nullable)(

16、BOOL isCanceled, BOOL isPassed, ZMStatusErrorType errorCode, NSString* _Nullable videoPath)callback;名称开始认证说明传入bizNO和merchantID开始芝麻验证。接口通过bizNO和 merchantID 初始化 SDK 接口，完成验证流程后回跳回原来的页面。验证的结果会通过callback进行回调。变量名说明类型bizNO业务串号，通过芝麻认证WebAPI获得NSString*merchantID商户号NSString*extParams额外的传入参数如果有视频录制的需求，则传入Recor

17、dVideo = YES否则传入 nil 即可；如果此处设置为要求录制视频，但初始化时使用了不返回视频地址的回调函数，则设置无效。NSDictionary*vc开启芝麻认证的页面UIViewController*callback回调函数函数2.2.3 ZMCertification.getVersion函数名getVersion+ (NSString *_nullable)getVersion;名称获取SDK的版本号类型说明函数说明无返回值NSString*一个字符串，表示当前SDK的版本号。如：ZMCert 1.0.0I2.2.4 ZMCertification的回调函数函数名callbac

18、kvoid(_nullable)(BOOL isCanceled, BOOL isPassed, ZMStatusErrorType errorCode)void(_nullable)(BOOL isCanceled, BOOL isPassed, ZMStatusErrorType errorCode, NSString* _Nullable videoPath)名称完成芝麻认证后回调类型说明函数说明无变量名说明类型isCanceled是否取消了芝麻认证，如果是则isPassed和errorCode的返回值均无意义。BOOLisPassed是否通过了芝麻认证，如果没有通过则返回errorCo

19、de表示失败的原因。BOOLerrorCode没有通过芝麻认证的原因，具体参见文档中的ZMStatusErrorType说明ZMStatusErrorTypevideoPath整个验证流程会录制成一个视频，如果RecordVideo = YES则将录制的视频保存在videoPath所对应的路径；如果没有要求录制视频，则返回 nilNSString*2.2.5 枚举ZMStatusErrorType类型名ZMStatusErrorType名称芝麻认证失败类型类型说明枚举类型说明枚举名说明值ZMStatusErrorNone无100ZMStatusErrorDeviceNotSupport手机在不

20、支持列表里101ZMStatusErrorNoPermission缺少手机权限102ZMStatusErrorFaceInit人脸采集算法初始化失败103ZMStatusErrorNetwork网络连接错误104ZMStatusErrorBizNo传入的bizNO 有误105ZMStatusErrorBundleId此APP的bundle_id在系统的黑名单库里106ZMStatusErrorDataSource数据源错误107ZMStatusErrorVerification用户人脸与数据库中的人脸比对分数较低108ZMStatusErrorInternal服务发生内部错误109ZMStat

21、usErrorUnmatchedMerchantIdbizNO和merchantID不匹配110ZMStatusErrorNoNetPermission没有联网权限111ZMStatusErrorNoCameraPermission没有打开相机的权限112ZMStatusErrorNoSensorPermission无法读取运动数据的权限113ZMStatusErrorVersionTooOldSDK版本过旧115ZMStatusErrorUseInfo身份证号和姓名的格式不正确116ZMStatusErrorBiznoLimitExceed身份证号和姓名在一天内使用次数过多117ZMStat

22、usErrorWrongSystemTime用户当前的设备时间与授权时间不符1183 SDK集成3.1 Android集成3.1.1 Android Studio（aar）l 把arr文件复制进入libs文件夹中（图1）图1l 在APP的gradle中加入（图2）repositories flatDirdirs libs并在dependencies 中加入compile(name:ZMCert_SDK, ext:aar)图2l 点击Rebuild Project即可3.1.2 Eclipse（Project Library）l 打开Eclipse的Package Explorerl 鼠标右键选

23、择new然后点击右侧的Project.。弹出对话框后打开Android文件夹然后双击Android Project from Existing Code选项会弹出新的对话框。再点击Browse按钮去选择刚刚下载好的demo，选择好后点击确定。这时会弹出新的对话框，里面会有两个工程被选择一个lib和一个project.再点击下面的finish按钮就回把两个工程导入Eclipse中。l 把两个工程导入eclipse后，鼠标放在lib工程上右键鼠标选择Properties点击打开，弹出对话框后选择Android选项。然后把右边的进度条拉到最底部，点击选中IS Library选择框。然后点击Apply

24、按钮最后点击ok按钮退出。l 再把鼠标移到project工程上右键鼠标选择Properties点击打开，弹出对话框后选择Android选项。然后把右边的进度条拉到最底部，点击add按钮这时会弹出对话框选择刚刚的lib点击OK按钮。然后点击Apply按钮最后点击ok按钮退出。l 集成完毕（可以clean一下你的工程）3.2 iOS集成3.2.1 将 ZMCert.framework 文件添加进入项目在 TARGETS-Build Phases- Link Binary With Libaries中点击“+”按钮，在弹出的窗口中点击“Add Other”按钮，选择 ZMCert.framework

25、添加到工程中。注: 静态库中采用Objective-C+实现，因此需要您保证您工程中至少有一个.mm后缀的源文件(您可以将任意一个.m后缀的文件改名为.mm)，或者在工程属性中指定编译方式，即在Xcode的Project - Edit Active Target - Build Setting 中找到 Compile Sources As，并将其设置为Objective-C+3.2.2 引入所需的系统库需要在您的Xcode工程中引入CoreMoton.framework和WebKit.framework、AVFoundation.framework、CoreMedia.framework、Co

26、reGraphics.framework。3.2.3 环境配置在TARGETS-Build Settings-Other Linker Flags 中添加-ObjC。3.2.4 引入 .bundle 资源文件选中工程名，在右键菜单中选择Add Files to “工程名”，选择 ZMCert.bundle文件，并勾选“Copy items if needed”复选框，单击“Add”按钮，将资源文件添加到工程中。3.2.5 引入头文件#import 3.2.6 一份简单的示例代码ZMCertification *manager = ZMCertification alloc init;manager startWithBizNO:TextView.textmerchantID:self.merchantView.textextParams:nil viewController:selfonFinish:(BOOL isCanceled, BOOL isPassed, ZMStatusErrorType errorCode) if (isCanceled) NSLog(用户取消了认证); else if (i