集成指南

1.SDK 目录结构

目录

2.将SDK集成到开发环境

使用 SDK 前,首先需要将其集成到您的开发环境中。

2.1 配置开发环境

2.1.1 一般集成方式

以银行卡Demo为例,身份证Demo同理。
  1. 首先使用android studio打开根目录下的 LFBankCardScanDemo

  2. 然后在app/build.gradle中修改成license绑定的包名,离线版用户此时可直接点击运行,体验银行卡Demo。

  3. 如果需要使用SDK提供的动态更新License机制,则需要打开com.linkface.bankcard包下面的LFConfig.java文件修改其中的

  public static final String LICENSE_INFO_URL = "https://cloud-license.linkface.cn/json/xxx.json";
  public static final int DAYS_BEFORE_LIC_EXPIRED = 5;

将LICENSE_INFO_URL的值修改为在我公司申请的License动态更新的链接;

将DAYS_BEFORE_LIC_EXPIRED的值修改为License需要动态更新下载提前的天数。

(离线版用户Demo已可以运行,在线版用户运行Demo请看下一步)

  1. online版本还需要打开com.linkface.bankcard包下面的LFConfig.java文件修改其中的

    public static final String APP_ID = "LF_CARD_APP_ID";
    public static final String APP_SECRET = "LF_CARD_APP_SECRET";
    

    将LF_CARD_APP_ID修改为在我公司申请的app_id;

    将LF_CARD_APP_SECRET修改为在我公司申请的app_secret;

在Android Studio中集成(Demo工程使用的第一种方式导入)

第一种集成方式(将UI层,即LFOCRUILib作为一个工程依赖)

  1. 新建一个android studio工程LFBankCardProject,然后将LFOCRUILib整个工程拷贝到和刚才新建的工程的同级目录下,如图 目录
  2. 在工程LFBankCardProject的根目录下的settings.gradle文件中加入

    includeFlat 'LFOCRUILib'

    include ':LFOCRUILib:LFCard'

  3. 添加依赖

    在新建应用的builde.gradle下添加

    repositories { flatDir {

     dirs '../../LFOCRUILib/LFCard/libs'
    

    } }

    在build.gradle中的dependencies{}中添加

    compile project(path: ':LFOCRUILib:LFCard')

    如下

  repositories {
    flatDir {
        dirs '../../LFOCRUILib/LFCard/libs'
    }
  }
  dependencies {
      compile project(path: ':LFOCRUILib:LFCard')
  }
  1. 此时可以跳转扫描界面,跳转方式,以及数据获取方式参考身份证使用流程或者银行卡使用流程

第二种集成方式(将UI层,即LFOCRUILib作为一个module导入)

  1. 新建一个android studio工程,然后点击File->New->Import Module,选择压缩包根录下LFOCRUILib工程中的LFCard模块,点击finish完成导入。
  2. 添加依赖,在新建应用的builde.gradle下添加

    repositories { flatDir {

     dirs '../LFCard/libs'
    

    } } 在build.gradle中的dependencies{}中添加compile project(':LFCard')

     repositories {
     flatDir {
         dirs '../LFCard/libs'
         }
     }
     dependencies {
       compile project(':LFCard')
     }
    
  1. 此时可以跳转扫描界面,跳转方式,以及数据获取方式参考身份证使用流程或者银行卡使用流程

2.1.2 直接集成aar包的方式

更灵活的集成方式,获取aar文件内容进行集成

1.将lfocrdetectlib.aar后缀重命名为.zip文件,解压。目录结构如图 目录

2.将解压目录中assets文件夹下的模型文件拷贝到 app/src/main/assets 目录中,如果使用银行卡扫描功能,则只需要拷贝 bankcard_2.6.model 和 bankextra1.0.model ;如果使用身份证扫描功能拷贝 idcard_3.0.0.model;两者都使用则拷贝全部 .model 文件

3.将解压目录中jni文件夹下的so文件夹拷贝到 app/src/main/jniLibs 目录中, 如果使用银行卡扫描功能,则只需要拷贝 libsdk_card.so 和 libst_bankcard.so 即可;如果使用身份证扫描功能,则只需要拷贝 libsdk_card.so 和 libst_idcard.so;两个功能都使用,则三个文件都要拷贝。

4.将 classes.jar 文件拷贝 app/libs 目录下。在builde.gradle添加依赖。注:可重命名该文件。

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

5.如果没有设置app_name会有一个报错,添加这个value 资源即可。

        android:label="@string/app_name"

2.2 配置 AndroidManifest.xml 文件

在 AndroidManifest.xml 中增加权限,代码如下:

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

2.3 添加License

将license目录下面的LinkfaceID.lic拷贝到工程的src/main/assets目录下面

2.4 解决代码混淆

如果不开启代码混淆则跳过这一步; 由于代码混淆后可能会发生crash,所以建议先在混淆配置中解决代码混淆问题。

具体操作为:在proguard文件中加入下面的代码解决:

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

2.5 初始化SDK识别模型

初始化SDK识别模型的代码:

LFBankCardScan.getInstance().initBankCardScan(getContext(), licenseName);

并处理可能抛出的异常。可用try...catch...语句包裹。详情可参考Demo。

2.6 获取数据

  1. 获取扫描结果图片离线版用户和在线版用户等同,请参考身份证接口调用流程银行卡接口调用流程

  2. 获取数据方式参考身份证接口调用流程银行卡接口调用流程,离线版用户获取到的IDCard和BankCard即为此次扫描结果数据,离线版结束,在线版请看下一步。

  3. 在线版用户获取到的IDCard和BankCard存储的是加密后的数据,需要调用解密接口获取数据,接口调用参考Demo中com.linkface.lfbankcardscandemo.result包下面的LFCardResultPresenter,接口说明文档银行卡参考ocr/parse_bankcard_ocr_result, 身份证参考ocr/parse_idcard_ocr_result
    Demo代码示例如下:
    if (mBankCard != null) {
     mCardResultPresenter.getCardViewData(mBankCard, new LFCardResultPresenter.ICardResultCallback() {
         @Override
         public void callback(LFBankCardViewData cardViewData) {
                 refreshBankCardView(cardViewData);
         }
         @Override
         public void fail(String error) {
             //解析数据失败
         }
     });
    
    }

3. License集成说明

我们的License中绑定了App包名有效期等信息。当授权出错时,SDK会返回错误码及Sample显示相应的提示语:

错误码 Sample提示语 描述
ERROR_LICENSE_PACKAGE_NAME_MISMATCH 绑定包名错误 集成SDK的工程包名与license文件绑定的包名不符
ERROR_LICENSE_EXPIRE License过期 license过期
ERROR_LICENSE_FILE_NOT_FOUND License不存在 LinkfaceID.lic的文件名或者路径被修改,导致无法找到License
ERROR_LICENSE_INVALID License不合法 SDK无法解析LinkfaceID.lic的内容

4. 证书动态更新使用指南

4.1 说明

  • OCR5.5版本开始支持动态传入License路径、检测license有效期、支持动态更新License;
  • License更新下载地址请联系market@linkface.cn;
  • 最新的License文件需向Linkface申请。
  • 备注:

    若不使用SDK提供的证书动态更新机制,以下内容可忽略。

    4.2 动态更新使用说明(详细可参考SDK Demo)

  • 注:将SDK集成完成,即可按此步骤使用银行卡SDK,身份证扫描SDK同理。
  • 4.2.1 传入License路径

    在APP使用SDK前初始化调用SDK方法传入License路径。如在APP首页Activity的onCreate中调用。

    String licPath = "/licSDKBankLicense/LinkfaceID.lic";
    LFBankCardScan.getInstance().initLicensePath(LFMainActivity.this, licPath, CardRecognizer.LICENSE_NAME);
    

    备注:

    licPath的值需要与动态更新下载License的存储路径保持一致,此路径是APP私有目录下的相对路径。 即,若APP私有目录为/data/user/0/<包名>/files,则License实际的存储路径为/data/user/0/<包名>/files/licSDKBankLicense/LinkfaceID.lic。

    4.2.2 获取License剩余有效天数

    返回license剩余有效天数

    int remainingDays = LFBankCardScan.getInstance().getRemainingDays(LFMainActivity.this);
    

    4.2.3 根据定制的更新License链接下载新License

    下载新License到指定路径

    if (!LFIDCardScan.getInstance().checkLicenseValid(this) || remainingDays < LFConstants.DAYS_BEFORE_LIC_EXPIRED) {
    LFLicDownloadManager.getInstance().downLoadLic(LFConstants.LICENSE_INFO_URL, LFIDCardScan.getInstance().getLicPath(), downloadListener);
    }
    

    4.3 License下载说明

    4.3.1 获取下载License信息的链接

    该链接为客户定制链接,请联系market@linkface.cn。

    4.3.2 License下载时序图

    时序图

    4.3.3 License信息格式

    License信息格式为Json。

    各字段及其说明

    字段名 说明
    md5 由license得到的MD5,32位小写
    start_time license有效期起始时间,Unix时间戳格式
    expired_time license有效期结束时间,Unix时间戳格式
    lic_url license下载地址

    json示例:

    { "md5": "qwertyhgfr567u8i987yt65rfghjkiuy", "start_time": 1517500800, "expired_time": 1546185600, "lic_url": "http://www.linkface.com/license_url" }

    4.3.4 License下载原理

    1. 根据定制链接请求License信息的Json数据;
    2. 根据Json数据中的lic_url下载License;
    3. 对该License内容做MD5得到32位小写字符串与License信息的json中md5字段的值进行比对,验证License;
    4. 将License放入初始化设置的路径中,替换原有License;
    5. 使用SDK提供的功能。

    4.4 同一应用同时集成Linkface的多个SDK的说明

    4.4.1 多个SDK使用同一License

    一般,同一应用的License是唯一的,所以集成不同SDK时只需要使用和管理一份License即可。 例如,先后集成了活体SDK和OCR SDK,集成活体SDK时,License路径为"/linkface/LinkfaceID.lic",该路径可以自定义。

    4.4.1.1 初始化时,使用同一License。

    活体SDK代码:

    String licPath = "/linkface/LinkfaceID.lic";
    String licName = "LinkfaceID.lic";
    //集成license动态更新机制,需传递licPath
    LFLivenessSDK.getInstance(MainTestActivity.this).initLicPath(licPath,licName);
    

    OCR SDK代码:

    String licPath = "/linkface/LinkfaceID.lic";
    LFBankCardScan.getInstance().initLicensePath(LFMainActivity.this, licPath, CardRecognizer.LICENSE_NAME);
    
    4.4.1.2 动态更新下载时,仅需要使用活体SDK或OCR SDK的一个SDK中判断License有效期并使用LFLicDownloadManager下载。

    详见4.2.3 根据定制的更新License链接下载新License

    4.4.2 多个SDK使用不同License

    4.4.2.1 初始化SDK

    需要将不同SDK初始化时的License路径设置为不同即可。如 活体SDK代码:

    String licPath = "/liveness/LinkfaceID.lic";
    String licName = "LinkfaceID.lic";
    //集成license动态更新机制,需传递licPath
    LFLivenessSDK.getInstance(MainTestActivity.this).initLicPath(licPath,licName);
    

    OCR SDK代码:

    String licPath = "/ocr/LinkfaceID.lic";
    LFBankCardScan.getInstance().initLicensePath(LFMainActivity.this, licPath, CardRecognizer.LICENSE_NAME);
    
    4.4.2.2 License动态更新

    因为License不同,所以需要分别动态更新License。详见4.2.3 根据定制的更新License链接下载新License

    results matching ""

      No results matching ""