移动端OCR识别SDK开发手册

(三证一卡、Vin码、车牌)

文件版本：V3.0.2

修改时间：2021-07-27

2

目录

说明....................................................................................................................................................4

1.1 硬件配置......................................................................................................................................4

1.2 授权..............................................................................................................................................4

1.3 iOS Demo 测试步骤......................................................................................................................4

1.4 Android Demo 测试步骤.............................................................................................................. 5

第一部分 二代证识别............................................................................................................... 10

· 二代证 Android 部分.....................................................................................................................10

· 二代证 iOS 部分............................................................................................................................ 17

二代证错误码...................................................................................................................................26

第二部分 银行卡识别............................................................................................................... 29

· 银行卡 Android 部分.....................................................................................................................29

· 银行卡 iOS 部分............................................................................................................................ 34

银行卡错误码...................................................................................................................................41

第三部分 驾驶证识别............................................................................................................... 43

· 驾驶证 Android 部分.....................................................................................................................43

· 驾驶证 iOS 部分............................................................................................................................ 48

驾驶证错误码...................................................................................................................................54

第四部分 行驶证识别............................................................................................................... 57

· 行驶证 Android 部分.....................................................................................................................57

· 行驶证 iOS 部分............................................................................................................................ 64

行驶证错误码...................................................................................................................................71

第五部分 Vin 码识别................................................................................................................. 74

· Vin 码 Android 部分........................................................................................................................74

· Vin 码 iOS 部分............................................................................................................................... 79

Vin 码错误码.....................................................................................................................................87

第六部分 车牌识别....................................................................................................................89

· 车牌 Android 部分.........................................................................................................................89

· 车牌 iOS 部分................................................................................................................................ 94

车牌错误码.......................................................................................................................................99

3

附录一 Android 接口参数描述.....................................................................................................101

附录二 常见问题...........................................................................................................................103

附录三 权限说明...........................................................................................................................107

4

说明

1.1 硬件配置

系统：支持 Android 4.0（API Level 15）到 Android 11（API Level 30）

支持 iOS 8.0 以上系统

CPU 架构： Android 支持: arm64-v8a、armeabi-v7a、armeabi、x86、x86_64

iOS 支持: i386、armv7、x86_64、arm64

支持机型：手机和平板。

硬件要求：要求设备上有相机模块。

网络：OCR 本地离线识别，无需网络

1.2 授权

用户在做测试和集成开发之前，需要向 SDK 提供商索取相关授权文件，授权

文件的名称即为授权码，将该文件直接添加到工程中编译即可。

1.3 iOS Demo测试步骤

步骤一：将授权文件拖入工程中，必须勾选Add to targets，否则会激活失败

报错22。

步骤二：修改AppDelegate.m中的AUTHCODE宏定义为当前授权文件名

步骤三：运行并测试(如果出现激活报错24，则需要修改Demo的BundleID为

申请授权时提供的BundleID，并清理缓存后运行，查看控制台打印的BundleID来

确认BundleID是否修改成功)

5

1.4 Android Demo测试步骤

步骤一: 将授权文件放入项目中,并且修改配置文件中的授权文件名称。

注: PlateInfoConfig为车牌示例配置文件，不同开发包对应不同Config文

件可自行修改配置.

步骤二:

①此文件为核心必备文件,更新需注意,如下图所示新增文件为:

6

xxx.bin xxx.dic xxx.param 3 种类型文件

nc_obj.bin 和 nc_obj.param 文件

②添加文件后，初始化需要注意的地方，例如:

③API 接口文件添加此参数:

7

④最后更新替换需要注意: 其他授权文件，以及识别库等直接替换覆盖即可.步骤三: 修改包名为授权绑定对应的app包名(若绑定app名以及其他类型可

对应修改相应的参数即可)。

步骤四：运行测试,如果出现授权信息失败 24 或 21，需要检查步骤 1,2 中是

否正确配置，以及读写权限是否开启，特别注意授权类型要配置正确。

8

测试激活失败错误码参考：

错误码 描述 备注

0 激活成功

20 未授权该产品

iOS:

授权中不包含当前测试的产品，需要联系商务申请包含该

产品的授权文件

Android:

1）产品类型值改为附录2指定的即可

2）授权中不包含当前测试的产品，需要联系商务申请包

含该产品的授权文件

21 未读取到授权文件

iOS：

模拟器运行会出现该报错，请使用真机测试

Android：

授权文件不存在或者读取不到，详见任一OCR产品的“配

置授权文件”步骤

22 公司未授权

iOS：

1）是否将授权文件拖入项目中且AppDelegate.m中宏定义

修改为lic文件名

2）删除授权重新拖入，拖入必须勾选Add to targets

4）不可修改授权文件名

23 无效授权

24 授权信息验证失败

iOS：

需要修改Demo的BundleID为申请授权时提供给我们的

9

BundleID

Andorid:

需要修改Demo的包名、app名为申请授权时提供给我们的

25 授权到期

1.授权文件到期，请联系我司业务人员。

2.若是不久刚出过授权，请确认是否替换最新的授权

30 SDK版本不符

授权绑定的SDK版本号和当前使用的SDK的版本号不一致

1.申请绑定了当前使用的SDK的版本号的授权

2.更换授权绑定的版本号对应的SDK

10

第一部分 二代证识别

· 二代证 Android 部分一、接口简介

(1) public native int SIDCardKernalInit (String szSysPath,String

filePath,String companyName int nProductType,int

nAultType,TelephonyManager telephonyManager,Context context);

功 能 初始化核心资源

参数

szSysPath 识别核心所在目录，传NULL即可

filePath 授权文件绝对路径

companyName 授权公司名称

nProductType 产品类型号，具体参考附录2

nAultType 授权类型号，具体参考附录1

telephonyManager

Android自带手机管理类，在程序中new出一个

即可

context 传this

返回值 0 表示成功，其他值失败（见常见问题激活失败）。

(2) public native void SIDCardKernalUnInit ();

功 能 释放核心资源

参 数 无

返回值 无

(3) public native int SIDCardSetRecogType(int nType);

11

功 能 设置识别类型

参 数 nType

0表示自动识别二代证面和反面；1表示只识别

二代证正面，2表示只二代证识别反面

返回值 0表示成功，其他值失败

(4) public native int SIDCardDetectNV21Corner(byte[]data,int nWidth,int

nHeight,int[]line_x,int[]line_y);

功 能 基于NV21字节流检测身份证四条边缘线

参 数

data NV21字节流数据

nWidth 适配相机预览宽度

nHeight 适配相机预览高度

line_X 一个长度为4的数组

line_y 一个长度为4的数组

返回值 3 成功，其他值未成功检测到身份证

(5) public native int SIDCardRecognizeNV21Corner(byte[]data,int

Width,int Height,int[]line_x,int[] line_y);

功 能 基于NV21字节流检线识别（和检线接口配套使用）

参 数

data NV21字节流数据

nWidth 适配相机预览宽度

nHeight 适配相机预览高度

line_X 一个长度为4的数组

line_y 一个长度为4的数组

返回值 0成功，其他值识别失败。

(6) public native int SIDCardRecognizeNV21 (byte[] ImageStreamNV21, int

nWidth, int nHeight, char[] szBuffer, int BufferLen);

12

功 能 基于NV21字节流识别（单独使用）

参 数

ImageStreamNV21 NV21字节流数据

nWidth 适配相机预览宽度

nHeight 适配相机预览高度

szBuffer 识别结果缓冲区

BufferLen 识别结果缓冲区长度

返回值 0成功，其他值识别失败。

(7) public native int SIDCardRecogImgaeFile (String path);

功 能 导入身份证图像识别

参 数 path 图像路径

返回值 0成功，其他值识别失败。

(8) public native String SIDCardGetResult (int nIndex);

功 能 获取各字段的识别内容

参 数 nIndex 字段索引值，详细见结尾字段索引表

返回值 各字段的识别内容。

(9) public native int SIDCardGetRecogType ();

功 能 获取识别类型

参 数 无

返回值 1表示识别的是二代证正面，2表示识别的是二代证反面，其他值失败

(10) public native int SIDCardSaveCardImage(String path);

功 能 保存证件图像

13

参 数 path 保存图像路径

返回值 0表示成功，其他值失败

(11) public native int SIDCardSaveHeadImage(String path);

功 能 保存身份证头像图

参 数 path 保存图像路径

返回值 0表示成功，其他值失败

(12) public native String SIDCardGetEndTime();

功 能 获取授权到期的日期

返回值 一个日期，格式如（“2018-1-1”）

(13) public native int SIDCardCheckLightSpotNV21Corner(byte[] data, int

Width, int Height, int[] line_x, int[] line_y);

功 能 判断是否反光

参 数

data NV21字节流数据

nWidth 适配相机预览宽度

nHeight 适配相机预览高度

line_X 一个长度为4的数组

line_y 一个长度为4的数组

返回值 1为反光 0为不反光

(14) public native int SIDCardCheckIsCopyNV21(byte[]data,int

Width,int Height,int[]line_x,int[] line_y);

功 能 基于NV21字节流检线识别（和检线接口配套使用）

参 数

data NV21字节流数据

nWidth 适配相机预览宽度

14

nHeight 适配相机预览高度

line_X 一个长度为4的数组

line_y 一个长度为4的数组

返回值 1为复印件 0为原件，其他值识别失败。

(15) public native int SIDCardSaveBaseImage(String path);

功 能 保存身份证原图

参 数 path 保存图像路径

返回值 0表示成功，其他值失败

二代证字段索引表

索引 字段名称

0 姓名

1 性别

2 民族

3 出生

4 地址

5 身份证号码

6 签发机关

7 有效期限

二、二代证SDK集成步骤

（1）如图所示：按照集成身份证库说明文档集成 IdcardLibrary 库

15

（2）配置识别库，配置授权文件,nc文件。

如图所示：将授权文件以及nc文件放到 assets 目录下

调用识别库的示例代码 和 接收识别结果的示例代码 可以参考 MainActivity

Sample 示例工程的 MainActivity 调用识别库的代码写的比较详细。

可请参考MainActivity。

（3）配置识别库，配置授权文件。

如图所示：找到 IdcardConfig 这个类，把 licenseId 的值改为自己授权

文件的名字

16

进入识别之前，加上如下代码：先初始化授权文件（完成授权文件配置）

EtopStreamUtil.initLicenseFile(MainActivity.this,IdcardConfig.licenseId);

（4）配置识别库，配置授权文件验证信息

如图所示：将 applicationId 改为自己授权文件绑定的包名

授权绑定包名说明：

比如授权绑定的包名为 com.etop.sample ，那么这个授权文件就只能用

在应用包名为 com.etop.sample 的应用上，用在其他包名的 app 上均激活

失败 ErrorCode 为 24

（5）在工程中配置相应的权限:

请您在自己的工程AndroidManifest.xml文件中添加如下权限：

<uses-permission android:name=\"android.permission.CAMERA\"/>

<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.VIBRATE\"/>

各个权限的用途说明：

17

CAMERA：调用相机进行相机预览扫描/拍照，识别相机中预览/拍照数据

READ_EXTERNAL_STORAGE：从相册选择图片识别，需要读取SD卡权限

WRITE_EXTERNAL_STORAGE：保存识别后的裁切图片，需要写入SD卡权限

VIBRATE：扫描识别成功，震动提示，需要震动权限

· 二代证 iOS 部分一、接口简介

1.1 二代证SDK接口简介

(1) - (int)initSIDCard:(NSString *)nsUserID nsReserve:(NSString *)

nsReserve;

功 能 初始化核心资源

参 数

nsUserID 授权码

nsReserve 保留参数，直接传nil

返回值 0表示成功，其他值失败（见附录1）

注：1.授权文件名不可更改！SDK会在内部校验授权文件名。

2.此方法读取授权文件时，先从沙盒的Documents中读取，如果找到授权文件则继续激活识

别核心，否则再在项目目录中寻找([NSBundle mainBundle])，如果找到授权文件则继续激活

识别核心，否则返回22。如图2.1所示。

18

图2.1 授权文件寻找方式

若您采用服务器端下载/更新授权文件的方式，请务必将授权文件保存至Documents目录下，

并以”nsUserID.lic”命名文件(例如传入的nsUserID为7332DBAFD2FD18301EF6，则下载并保存到

沙盒的授权文件应命名为7332DBAFD2FD18301EF6.lic)。如图2.2所示。

图2.2 授权文件路径示例

建议此方式下，在项目目录中也放一个授权文件，没网的情况下也能使用。由于是优先读取

网络下载的授权文件，所以项目目录中的授权文件存在不会影响读取从网络下载的最新的授

权。

(2) - (int)freeSIDCard;

功 能 释放核心资源

参 数 无

返回值 0表示释放成功

(3) - (int)setRecognizeType:(int)nType;

功 能 设置识别类型

参 数 nType 证件类型（0-自动、1-正面、2-背面）

返回值 0成功，其他值失败（见附录1）

19

(4) - (int)recognizeSIDCard:(UInt8 *)buffer Width:(int)width

Height:(int)height;

功 能 视频预览识别

参 数

buffer 图像数据地址

width 图像宽度

height 图像高度

返回值 0为识别成功，-1为识别失败（实时识别，失败值不作为判断依据）

(5) - (int)recognizeSIDCardPhoto:(UIImage *)image;

功 能 (视频流识别使用)拍照识别

参 数 image 图像实例

返回值 0为识别成功，-1为识别失败

(6) - (int)recognizeSIDCardImage:(UIImage *)image;

功 能 系统相机/相册导入识别

参 数 image 图像实例

返回值 0为识别成功，-1为识别失败

(7) - (int)getRecognizeType;

功 能 获取证件类型

参 数 无

返回值 返回证件类型（1-正面、2-背面）

(8) - (int)getIDCardDirection;

功 能 获取证件方向

参 数 无

返回值 返回证件方向（0-0度、1-180度）

(9) - (int)SIDCardCheckIsCopy;

20

功 能 判断是否为复印件

参 数 无

返回值 返回（0-否、1-是、-1-错误）

(10) -(int)detectSIDCardSideWithImage:(UIImage *)image

lastDetect:(BOOL)bLastDetect corner:(NSMutableArray *)cornerArray;

功 能 图像检四边

参 数

image 图像实例

bLastDetect 是否是最后一帧

cornerArray

返回检测到的四个顶点（左上、右上、右下、

左下）

返回值 0成功，其他值失败（见附录1）

(11) - (int)recognizeSIDCard:(UIImage *)image corners:(NSMutableArray *)

corner;

功 能 (视频流预览识别使用)识别(四边界点)

参 数

image 图像实例

corner 传入检测到的四个顶点（左上、右上、右下、

左下）

返回值 0成功，其他值失败（见附录1）。

(12) - (void)configVerifyParam:(int)verifyType;

功 能 配置校验

参 数 verifyType

0-(默认值) 所有校验规则 1-去除地址校验

2-去除签发机关校验 3-去除地址和签发机关

校验

返回值 0无。

(13) - (int)checkLightSpot:(UIImage *)image corners:(NSMutableArray *)

corner;

功 能 (视频流预览识别使用)检测是否有反光

21

参 数

image 图像实例

corner 传入证件在图片中的四个顶点的位置（左上、

右上、右下、左下）

返回值 0无反光，1有反光，-1四个顶点错误

参数列表

参数类型 参数名 类型 释义

OCR字段

nsName NSString 姓名

nsSex NSString 性别

nsNation NSString 民族

nsBirth NSString 出生日期

nsAddress NSString 地址

nsIDNum NSString 身份证号

nsIssuingAuthority NSString 签发机关

nsExpDate NSString 有效期限

图像相关

imageHead UIImage 人像裁切图

imageCard UIImage 二代证裁切图

其他

nsEndTime NSString 授权到期时间

pathForIDCard NSString

授权文件/模型文件

读取地址(插件化使

用)

sdkVersion NSString 核心库版本号

needIDCardDebugLog BOOL 需要打印调试信息

1.2 封装接口简介

(1) + (instancetype)sharedManager;

功 能 单例全局访问点

22

参 数 无

返回值 单例对象

(2) - (void)recognizeIDCardWithImage:(UIImage *)cardImage

andAuthCode:(NSString *)authCode;

功 能 拍照/导入识别封装接口

参 数

cardImage 需要识别的图像

authCode 授权文件名

返回值 无

(3) -

(void)recognizeIDCardByVideoStreamWithController:(UIViewController

*)parentController recognizeFront:(BOOL)isFront

isUsePush:(BOOL)usePush isVibrateWhenSuccess:(BOOL)isVibrate

andAuthCode:(NSString *)authCode;

功 能 视频流预览识别封装接口

参 数

parentController 当前控制器(self)

isFront 默认识别人像面/国徽面[YES-人像面 NO-国

徽面]

usePush 是否使用push弹出裁剪控制器[YES-push

NO-modal(模态弹出)]

isVibrate 识别成功时是否振动提示

authCode 授权文件名

返回值 无

1.3 回调函数简介(IDCardManagerDelegate)

(1) - (void)recognizeIDCardPhotoFinishWithSrcImage:(UIImage *)srcImage

cardImage:(UIImage *)cardImage headImage:(UIImage *)headImage

result:(NSDictionary *)resultDic andErrorCode:(int)errorCode;

23

功 能 拍照/导入识别回调

参 数

srcImage 识别传入的身份证图片

cardImage 身份证裁切图

headImage 人像图

resultDic 识别结果

errorCode 识别结果(0-识别成功,-1-识别失败)

返回值 无

(2) - (void)cameraController:(UIViewController *)cameraController

managerRecognizeIDCardByVideoStreamFinishWithResult:(NSDictionary

*)resultDic isFrontOrBack:(int)frontOrBack cardImage:(UIImage

*)cardImage headImage:(UIImage *)headImage andSrcImage:(UIImage

*)srcImage;

功 能 视频流预览识别回调

参 数

cameraController 自定义相机控制器

resultDic 识别结果

frontOrBack 识别的是正面/背面(1-front 2-Back 0-未知

(拍照识别识别失败返回该值))

cardImage 身份证裁切图

headImage 人像图

srcImage 原图(无裁切，带背景)

返回值 无

注：参数 resultDict 为识别结果，字段值如下。（“反光检测”仅视频流识别有）

frontOrBack == 1(正面)

@\"姓名\",@\"性别\",@\"民族\",@\"出生日期\",@\"住址\",@\"身份证号\",@\"是否为复印

件\",@\"反光检测\" frontOrBack == 2(背面)

@\"签发机关\",@\"有效期\",@\"是否为复印件\",@\"反光检测\"二、二代证SDK集成步骤

步骤一：将授权文件和Demo中的IDCard文件夹拖入工程中，拖入授权文件

时请选择Copy items if needed、Create groups和Add to targets。

24

步骤二：在控制器内#import \"IDCardManager.h\"步骤三：

如果是相册导入/系统相机拍照识别，在

- (void)imagePickerController:(UIImagePickerController *)picker

didFinishPickingMediaWithInfo:(NSDictionary<NSString *,id> *)info;方法内

调用下图中所示方法即可识别。(详见Demo)(打开系统相机/相册那部分代码在此不做介

绍，不会写可参考Demo)

实现如下代理方法即可获得导入/拍照识别的识别结果。(详见Demo)

如果是视频流预览识别，在点击事件内调用如下方法即可弹出相机界面开

始识别。(详见Demo)

25

实现如下代理方法即可获得视频流识别的识别结果。(详见Demo)

注意：Demo中在系统相机拍照识别/相册导入识别的识别前后加了一些线程间通

信，在实际项目中可不写。Demo中需要使用SVProgressHUD来提供识别时的转圈

动画，识别操作属于耗时操作放在主线程阻塞UI，转圈动画无法显示出来。集成

到项目中后若不开子线程即能满足需求则可不加线程间通信代码，开启子线程与

否不影响识别准确率，识别速度差距基本可忽略。

步骤四：需要在Info.plist配置相应的相机和相册权限，否则会崩溃。

相机权限 NSCameraUsageDescription

相册权限

NSPhotoLibraryUsageDescription

≥iOS11.0(相册

写入操作需要) NSPhotoLibraryAddUsageDescription

步骤五：添加依赖库

导入识别：

MobileCoreServices.framework

视频流预览识别：

AVFoundation.framework

CoreMedia.framework

AudioToolbox.framework

步骤六：在Info.plist添加View controller-based status bar appearance,设为

NO。以允许我们在相机控制器改变状态栏的颜色。（若已添加请忽略）

26

通用激活错误码

错误码 描述 备注

0 激活成功

20 未授权该产品

iOS:

授权中不包含当前测试的产品，需要联系商务申请包含该

产品的授权文件

Android:

2）产品类型值改为附录2指定的即可

2）授权中不包含当前测试的产品，需要联系商务申请包

含该产品的授权文件

21 未读取到授权文件

iOS：

模拟器运行会出现该报错，请使用真机测试

Android：

授权文件不存在或者读取不到,详见配置授权文件

22 公司未授权

iOS：

1）如果是Demo测试：是否将授权文件拖入项目中且

AppDelegate.m中宏定义修改为lic文件名

2）项目targets->Build Phases->Copy Bundle Resources，点

击+号把授权文件进去，再次运行

3）清除缓存(替换新授权后可能会出现报错22)

4）不可修改授权文件名

23 无效授权

24 授权信息验证失败

iOS：

检查项目的BundleID和申请授权时提供给我们的BundleID

是否相同

Andorid:

需要项目的信息是否与授权绑定的信息一致,比如包名、

app名

25 授权到期

1.授权文件到期，请联系我司业务人员。

2.若是不久刚出过授权，请确认是否替换最新的授权

26 nsUserID为空 传入的nsUserID为空字符串或者nil

30 SDK版本不符

授权绑定的SDK版本号和当前使用的SDK的版本号不一致

3.申请绑定了当前使用的SDK的版本号的授权

4.更换授权绑定的版本号对应的SDK

二代证独有激活错误码

错误码 描述 备注

0 成功

27

2 初始化字典失败

可能重复激活核心。确定激活核心和释放核心代码是否成

对出现。

3 深度学习核心文件读

取失败

.dic.param等文件

4/5/6/7/

8

深度学习核心文件初

始化失败

文件是否损坏或配置正确

10

(iOS)复制模型文件失

败

查看控制台输出的copy error信息

49

(iOS)找不到NCBundle

文件

1.是不是没将模型文件(IDCardNCResource.bundle拖入项

目

2.是不是拖入的时候没勾选AddToTargets

3.是否将bundle文件改名以及bundle文件内的三个文件改

名

二代证检线错误码

错误码 描述 备注

0 检测不到线

1 第一次检测到

3 检测到线

二代证识别错误码

错误码 描述 备注

通用

0 识别成功

1 加载图片数据失败 图像损坏等原因

3 图像处理失败

-1 加载图片数据失败 图像损坏等原因

-5 识别失败 识别身份证号

正页

1 识别结果获取小于1

2 图像解析失败 图像数据有问题

-1 点检边失败

-2 有效期校验失败

28

副页

-2 识别失败 识别地址失败

-3 识别失败 正页其中一个数据识别为空

29

第二部分 银行卡识别

· 银行卡 Android 部分一、接口简介

1.1 银行卡 SDK 接口简介

(1) public native int ScanStart(String szSysPath,String filePath,String

userId int nProductType,int nAultType,TelephonyManager

telephonyManager,Context context);

功能 初始化核心资源

参数

szSysPath 识别核心所在目录，传NULL即可

filePath 授权文件绝对路径

userId 授权码，由sdk供应商提供

nProductType 产品类型号，具体参考附录2

nAultType 授权类型号，具体参考附录1

telephonyManager

Android自带手机管理类，在程序中new出一个即

可

context 传this

返回值 0 表示成功，其他值失败（见 常见问题 - 激活失败）。

(2) public native void ScanEnd ();

功能 释放核心资源

参数 无

返回值 无

30

(3) public native void SetRegion (int left,int top,int right,int bottom);

功能 设置拍摄界面中银行卡的矩形识别区域

参数

left 矩形左边

top 矩形右边

right 矩形上边

bottom 矩形下边

返回值 无

(4) public native int ScanStreamNV21(byte[] streamnv21, int cols, int

raws, int []line,char[] cardno, int []wrapdata);

功能 基于NV21字节流识别

参 数

streamnv21 NV21字节流数据

cols 适配相机预览宽度

raws 适配相机预览高度

line

int类型数组，长度为4，返回四边检测情况，，

1表示检测到了边，0表示没检测到边

cardno 识别结果

wrapdata 返回一个400*80的图片数据

返回值 0成功，其他值失败

(5) public native int ScanImage(String ImagePath,char[] cardNo);

功能 导入图像识别接口

参 数 ImagePath：图像路径；cardNo：识别出卡后的信息

返回值 0成功，其他值失败，表示未发现银行卡

(6) public native int InitCardInfo();

31

功能 初始化银行卡其他信息的核心

参 数 无

返回值 0成功，其他值失败

(7)public native int UninitCardInfo();

功能 释放卡其他信息的核心资源

参数 无

返回值 无

(8) public native int GetCardInfo(char[] cardno,String[] cardinfo);

功能 根据卡号，获取其他信息

参数

Cardno，识别出的卡后

Cardinfo：返回的卡片信息，数组的长度要大于等于4!

cardinfo[0]:银行名称

cardinfo[1]:卡名称

cardinfo[2]:银行代码

cardinfo[3]:卡类型

返回值 0成功，其他值失败

(9) public native String GetEndTime ();

功能 获取授权文件的截止日期

参 数 无

返回值 返回授权的截止日期，在初始化核心成功之后调用

二、银行卡SDK集成步骤

（1）如图所示：按照集成银行卡库说明文档集成 BankLibrary 库

32

（2）配置识别库，配置授权文件。

如图所示：将授权文件放到 assets 目录下

调用识别库的示例代码 和 接收识别结果的示例代码 可以参考 MainActivity

Sample 示例工程的 MainActivity 调用识别库的代码写的比较详细。

可请参考MainActivity。

（3）配置识别库，配置授权文件。

如图所示：找到 BankConfig 这个类，把 licenseId 的值改为自己授权文件的

名字

33

进入识别之前，加上如下代码：先初始化授权文件（完成授权文件配置）

EtopStreamUtil.initLicenseFile(MainActivity.this,BankConfig.licenseId);

（4）配置识别库，配置授权文件验证信息

如图所示：将 applicationId 改为自己授权文件绑定的包名

授权绑定包名说明：

比如授权绑定的包名为 com.etop.sample ，那么这个授权文件就只能用

在应用包名为 com.etop.sample 的应用上，用在其他包名的 app 上均激活失

败 ErrorCode 为 24

（5）在工程中配置相应的权限:

请您在自己的工程AndroidManifest.xml文件中添加如下权限：

34

<uses-permission android:name=\"android.permission.CAMERA\"/>

<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.VIBRATE\"/>

各个权限的用途说明：

CAMERA：调用相机进行相机预览扫描/拍照，识别相机中预览/拍照数据

READ_EXTERNAL_STORAGE：从相册选择图片识别，需要读取SD卡权限

WRITE_EXTERNAL_STORAGE：保存识别后的裁切图片，需要写入SD卡权限

VIBRATE：扫描识别成功，震动提示，需要震动权限

· 银行卡 iOS 部分一、接口简介

1.1 银行卡SDK接口简介

1) SBankCard:

(1) - (int)initSBankCard:(NSString *)nsUserID nsReserve:(NSString *)

nsReserve;

功 能 初始化核心资源

参 数

nsUserID 授权码/授权文件名

nsReserve 保留参数，直接传nil

返回值 0表示成功，其他值失败（见附录1）

注：授权文件和深度学习模型文件读取路径顺序：

1.用户设定地址

2.沙盒

3.[NSBundle mainBundle]

(2) - (int)freeSBankCard;

功 能 释放核心资源

参 数 无

返回值 0表示成功

(3) - (void)setRegionWithLeft:(int)nLeft Top:(int)nTop Right:(int)nRight

Bottom:(int)nBottom;

35

功 能 设置银行卡的检测区域

参 数

nLeft 左边界

nTop 上边界

nRight 右边界(左边界+宽度)

nBottom 下边界(上边界+高度)

返回值 无

(4) - (int)recognizeSBankCard:(UInt8 *)buffer Width:(int)width

Height:(int)height;

功 能 视频流识别

参 数

buffer 图像数据地址

width 图像宽度

height 图像高度

返回值

0表示成功，1、2表示识别失败(实时识别，失败的值不作为判断依据)，

19表示未初始化核心导致识别失败

(5) - (int)recognizeSBankCardImage:(UImage *)image;

功 能 系统相册导入/系统相机拍照识别

参 数 image 图像实例

返回值 0表示成功，19表示识别失败

(6) - (void)setRecognizeType:(int)type;

功 能 设置识别类型

参 数 type 0-横屏 1-竖屏

返回值 无

参数列表

参数类型 参数名 类型 释义

OCR字段

nsNo NSString 银行卡号

nsValidThru NSString 有效日期

图像相关

resultImg UIImage 卡号裁切图

bankCardImg UIImage 银行卡裁切图

其他

nsEndTime NSString 授权到期时间

pathForBC NSString

授权文件/模型文件

读取地址(插件化使

36

用)

sdkVersion NSString 核心库版本号

needBCLog BOOL 需要打印调试信息

2) SBankCardInfo:

(1) -(int)initSBankCardInfo;

功 能 初始化核心资源

参 数 无

返回值 0表示成功，其他值失败（见附录1）

(2) - (void)freeSBankCardInfo;

功 能 释放核心资源

参 数 无

返回值 无

(3) - (int)getSBankCardInfo:(NSString *)nsBankCardNo;

功 能 通过银行卡号获取银行卡信息

参 数 nsBankCardNo 银行卡号

返回值 1表示成功，0表示失败

参数列表

参数类型 参数名 类型 释义

字段

nsBankName NSString 开户行名称

nsCardName NSString 银行卡名称

nsBankCode NSString 银行代码

nsCardType NSString 银行卡类型

其他 sdkVersion NSString 核心库版本号

1.2 封装接口简介

(1) + (instancetype)sharedManager;

37

功 能 单例全局访问点

参 数 无

返回值 单例对象

(2) - (void)recognizeBankCardWithImage:(UIImage *)bcImage

andAuthCode:(NSString *)authCode;

功 能 拍照/导入识别封装接口

参 数

bcImage 需要识别的图像

authCode 授权文件名

返回值 无

(3) -

(void)recognizeBankCardByVideoStreamWithController:(UIViewController

*)parentController isUsePush:(BOOL)usePush

isVibrateWhenSuccess:(BOOL)isVibrate andAuthCode:(NSString *)authCode;

功 能 视频流预览识别封装接口

参 数

parentController 当前控制器(self)

usePush 是否使用push弹出裁剪控制器[YES-push

NO-modal(模态弹出)]

isVibrate 识别成功时是否振动提示

authCode 授权文件名

返回值 无

1.3 回调函数简介(BankCardManagerDelegate)

(1) - (void)recognizeBankCardPhotoFinishWithImage:(UIImage *)bcImage

result:(NSDictionary *)resultDic andErrorCode:(int)errorCode;

功 能 拍照/导入识别回调

参 数

bcImage 识别传入的银行卡图片

resultDic 识别结果

errorCode 识别结果(0-识别成功,19-识别失败)

返回值 无

(2) - (void)cameraController:(UIViewController *)cameraController

recognizeBankCardByVideoStreamFinishWithImage:(UIImage *)bcImage

bankNumberAreaImage:(UIImage *)numAreaImage srcImage:(UIImage

*)srcImage andResult:(NSDictionary *)resultDic;

38

功 能 视频流预览识别回调

参 数

cameraController 自定义相机控制器

bcImage 银行卡裁切图

numAreaImage 截取的银行卡号码区域的图片(400*70)

srcImage 完整原图

resultDic 识别结果

返回值 无

成员变量：参数 resultDict 为识别结果，字段值如下。

@\"银行卡号\",@\"发卡行名称\",@\"银行卡名称\",@\"银行卡种\",@\"机构代码\"二、银行卡SDK集成步骤

步骤一：将授权文件和BankCard文件夹拖入工程中，拖入授权文件时请选

择Copy items if needed、Create groups和Add to targets。

步骤二：在控制器内#import \"BankCardManager.h\"步骤三：

如果是相册导入/系统相机拍照识别，先#import \"REEditController.h\"，

并在

39

- (void)imagePickerController:(UIImagePickerController *)picker

didFinishPickingMediaWithInfo:(NSDictionary<NSString *,id> *)info;方法内

调用下图中所示方法进入编辑界面。(详见Demo)(打开系统相机/相册那部分代码在此不

做介绍，不会写可参考Demo)

实现代理方法即可拿到裁切后的图。

实现如下代理方法即可获得导入/拍照识别的识别结果。(详见Demo)

如果是视频流预览识别，在点击事件内调用如下方法即可弹出相机界面开

始识别。(详见Demo)

40

实现如下代理方法即可获得视频流识别的识别结果。(详见Demo)

注意：Demo中在导入/拍照识别的识别前后加了一些线程间通信，在实际项目中

可不写。Demo中需要使用SVProgressHUD来提供识别时的转圈动画，识别操作属

于耗时操作放在主线程阻塞UI，转圈动画无法显示出来。集成到项目中后若不开

子线程即能满足需求则可不加线程间通信代码，开启子线程与否不影响识别准确

率，识别速度差别基本可忽略。

步骤四：需要在Info.plist配置相应的相机和相册权限，否则会崩溃。

相机权限 NSCameraUsageDescription

相册权限

NSPhotoLibraryUsageDescription

≥iOS11.0(相册

写入操作需要) NSPhotoLibraryAddUsageDescription

步骤五：添加依赖库

导入识别：

MobileCoreServices.framework

视频流预览识别：

AVFoundation.framework

CoreMedia.framework

AudioToolbox.framework

步骤六：在Info.plist添加View controller-based status bar appearance并设为

NO。以允许我们在相机控制器改变状态栏的颜色。（若已添加请忽略）

41

通用激活错误码

错误码 描述 备注

0 激活成功

20 未授权该产品

iOS:

授权中不包含当前测试的产品，需要联系商务申请包含该

产品的授权文件

Android:

3）产品类型值改为附录2指定的即可

2）授权中不包含当前测试的产品，需要联系商务申请包

含该产品的授权文件

21 未读取到授权文件

iOS：

模拟器运行会出现该报错，请使用真机测试

Android：

授权文件不存在或者读取不到,详见配置授权文件

22 公司未授权

iOS：

1）如果是Demo测试：是否将授权文件拖入项目中且

AppDelegate.m中宏定义修改为lic文件名

2）项目targets->Build Phases->Copy Bundle Resources，点

击+号把授权文件进去，再次运行

3）清除缓存(替换新授权后可能会出现报错22)

4）不可修改授权文件名

23 无效授权

24 授权信息验证失败

iOS：

检查项目的BundleID和申请授权时提供给我们的BundleID

是否相同

Andorid:

需要项目的信息是否与授权绑定的信息一致,比如包名、

app名

25 授权到期

1.授权文件到期，请联系我司业务人员。

2.若是不久刚出过授权，请确认是否替换最新的授权

30 SDK版本不符

授权绑定的SDK版本号和当前使用的SDK的版本号不一致

5.申请绑定了当前使用的SDK的版本号的授权

6.更换授权绑定的版本号对应的SDK

银行卡独有激活错误码

错误码 描述 备注

0 成功

1 初始化字典失败 重复激活核心。确定激活核心和释放核心代码是否成对出

42

现。

7 关键文件获取失败 如核心文件等

26 nsUserID为空 检查激活核心时传入的nsUserID是不是nil或空字符串

银行卡识别错误码

错误码 描述 备注

0 识别成功

1 检线失败/图像处理失

败

2

识别失败/图像解析失

败

图像数据有问题

19 识别失败

43

第三部分 驾驶证识别

· 驾驶证 Android 部分一、驾驶证接口简介

(1) public native int DLKernalInit (String szSysPath,String filePath,String

companyName int nProductType,int nAultType,TelephonyManager

telephonyManager,Context context);

功能 初始化核心资源

参数

szSysPath 识别核心所在目录，传NULL即可

filePath 授权文件绝对路径

companyName 授权公司名称

nProductType 产品类型号，具体参考附录2

nAultType 授权类型号，具体参考附录1

telephonyManager

Android自带手机管理类，在程序中new出一个

即可

context 传this

返回值 0 表示成功，其他值失败（见常见问题-激活失败）。

(2) public native void DLKernalUnInit ();

功能 释放核心资源

参数 无

返回值 无

(3) public native int DLDetectLine(byte[] data, int nWidth, int nHeight,

44

int []LineX,int[]LineY);

功能 基于NV21字节流检测证件自动拍照

参 数

data NV21字节流数据

nWidth 适配相机预览宽度

nHeight 适配相机预览高度

LineX[] 检测到的四点横坐标(数组大小为4)

LineY[] 检测到的四点纵坐标(数组大小为4)

返回值 0成功，其他值表示检测状态(见附录3)

(4) public native int DLRecognizePhoto (byte[] data, int nLen);

功能 拍照识别驾驶证正页

参 数

data 拍照图像jpg数据

nLen data数据的长度

返回值 0表示成功，其他值失败（原因：图像中未发现驾照、图像不清晰）

(5) public native int DLDeputyPageRecognizePhoto (byte[] data, int nLen);

功能 拍照识别驾驶证副页

参 数

data 拍照图像jpg数据

nLen data数据的长度

返回值 0表示成功，其他值失败（原因：图像中未发现驾照、图像不清晰）

(6) public native int DLRecognizeImageFileW(String imgPath);

功能 导入识别驾驶证正页

参 数 imgPath 需要识别的图像路径

返回值 0成功，其他值失败（原因：图像中未发现驾照、图像不清晰）

45

(7) public native int DLRecogDeputyPageImage(String imgPath);

功能 导入识别驾驶证副页

参 数 imgPath 需要识别的图像路径

返回值 0成功，其他值失败（原因：图像中未发现驾照、图像不清晰）

(8) public native String DLGetResult (int nIndex);

功能 获取各字段的识别内容

参 数 nIndex 字段索引值，详细下面驾驶证字段索引表

返回值 各字段的识别内容。驾驶证字段索引表

索引 字段名称

0 证号

1 姓名

2 性别

3 住址

4 初始领证日期

5 准驾车型

6 有效初始日期

7 有效期限/有效期至

8 国籍

9 出生日期

46

二、驾驶证SDK集成步骤

（1）如图所示：按照集成驾驶证库说明文档集成 DriveLicenseLibrary 库

（2）配置识别库，配置授权文件。

如图所示：将授权文件放到 assets 目录下

调用识别库的示例代码 和 接收识别结果的示例代码 可以参考 MainActivity

Sample 示例工程的 MainActivity 调用识别库的代码写的比较详细。

可请参考MainActivity

（3）配置识别库，配置授权文件。

如图所示：找到 IdcardConfig 这个类，把 licenseId 的值改为自己授权文件

的名字

47

进入识别之前，加上如下代码：先初始化授权文件（完成授权文件配置）

EtopStreamUtil.initLicenseFile(MainActivity.this,DriveLicenseConfig.licenseId);

（4）配置识别库，配置授权文件验证信息

如图所示：将 applicationId 改为自己授权文件绑定的包名

授权绑定包名说明：

比如授权绑定的包名为 com.etop.sample ，那么这个授权文件就只能用

在应用包名为 com.etop.sample 的应用上，用在其他包名的 app 上均激活失

败 ErrorCode 为 24

（5）在工程中配置相应的权限:

请您在自己的工程AndroidManifest.xml文件中添加如下权限：

<uses-permission android:name=\"android.permission.CAMERA\"/>

<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>

<uses-permission android:name=\"android.permission.VIBRATE\"/>

48

各个权限的用途说明：

CAMERA：调用相机进行相机预览扫描/拍照，识别相机中预览/拍照数据

READ_EXTERNAL_STORAGE：从相册选择图片识别，需要读取SD卡权限

WRITE_EXTERNAL_STORAGE：保存识别后的裁切图片，需要写入SD卡权限

VIBRATE：扫描识别成功，震动提示，需要震动权限

· 驾驶证 iOS 部分一、驾驶证接口简介

1.1 SDK接口简介

(1) - (int)initDriveLicense:(NSString *)nsUserID nsReserve:(NSString *)

nsReserve;

功 能 初始化核心资源

参 数

nsUserID 授权码/授权文件名

nsReserve 保留参数，直接传nil

返回值 0表示成功，其他值失败（见附录1）。

(2) - (int)freeDriveLicense;

功 能 释放核心资源

参 数 无

返回值 0表示成功

(3) - (int)detectDriveLicenseSide:(UInt8 *)buffer Width:(int)width

Height:(int)height Corner:(NSMutableArray *) cornerArray;

功 能 检测证件四个角在图片中的位置

参 数

buffer 图像数据地址

width 图像宽度

height 图像高度

cornerArray

返回证件四个顶点位置（顺序：左上、右上、

右下、左下）

返回值 0表示成功，其他值（31、32、33、34）失败（见附录1）。

(4) - (int)recognizeDriveLicense:(UInt8 *)buffer Width:(int)width

Height:(int)height;

49

功 能 视频预览识别

参 数

buffer 图像数据地址

width 图像宽度

height 图像高度

返回值 0表示成功，其他值失败（见附录1）。

(5) - (int)recognizeDriveLicensePhoto:(UIImage *)image;

功 能 拍照识别

参 数 image 图像实例

返回值 0表示成功，其他值失败（见附录1）。

(6) - (int)recognizeDriveLicenseImage:(UIImage *)image;

功 能 导入识别

参 数 image 图像实例

返回值 0表示成功，其他值失败（见附录1）。

参数列表

参数类型 参数名 类型 释义

OCR字段

nsIDNo NSString 证号

nsName NSString 姓名

nsSex NSString 性别

nsNationality NSString 国籍

nsBirthday NSString 出生日期

nsAddress NSString 地址

nsIssueDate NSString 初次领证日期

nsIssuingAuthority NSString 签发机关

nsClass NSString 准驾车型

nsValidFrom NSString 有效起始日期

nsValidFor NSString 有效期限

nsDeputyPageID NSString 副页证号

50

nsDeputyPageNO NSString 副页档案编号

图像相关 resultImg UIImage

裁切图(1280*720)(暂

无返回)

其他

nsEndTime NSString 授权到期时间

pathForDL NSString

授权文件/模型文件

读取地址(插件化使

用)

sdkVersion NSString 核心库版本号

needDLLog BOOL 需要打印调试信息

1.2 封装接口简介

(1) + (instancetype)sharedDLManager;

功 能 单例全局访问点

参 数 无

返回值 单例对象

(2) - (void)recognizeDLWithController:(UIViewController

*)parentController licencePhoto:(UIImage *)licencePhoto

isNeedTailor:(BOOL)needTailor isUsePush:(BOOL)usePush

authCode:(NSString *)authCode andIsFrontPage:(BOOL)isFrontPage;

功 能 拍照/导入识别封装接口

参 数

parentController 当前控制器(传self)

licencePhoto 驾驶证图片

needTailor 是否需要剪裁

usePush 是 否 使 用 push 弹 出 控 制 器 (YES-Push

NO-Modal)

authCode 授权文件名

isFrontPage 是否是正页(YES-正页 NO-副页)

返回值 无

(3) - (void)recognizeDLByVideoStreamWithController:(UIViewController

*)parentController isUsePush:(BOOL)usePush authCode:(NSString