集成指南

1.SDK 目录结构

目录

2.准备工作

2.1 获取SDK Demo压缩包、License文件、License下载链接

请联系您的Linkface专属商务获取SDK Demo压缩包及License文件;

若需要使用SDK Demo的License动态更新机制,请同时向商务索要License的下载链接;

商务邮箱:market@linkface.cn

2.2 获取APP_KEY、 APP_SECRET

此部分针对使用SDK online版本的用户,offline版本用户可忽略。

  1. 访问Linkface官网https://www.linkface.cn ,点击右上角“管理中心”;
  2. 按照流程提示完成账号的注册及登录,添加应用;
  3. 在应用管理界面,可以看到您应用的API ID、API SECRET,即SDK中需要使用的APP_KEY,、APP_SECRET。 获取APP_KEY、 APP_SECRET

3.Demo示例

  1. 使用Android Studio打开SDK压缩包中的项目,银行卡识别Demo或身份证识别Demo,如下图 打开Demo

  2. 找到项目中LFConfig.java文件。offline版Demo中如下 LFConfig.java文件 需要注释掉“注意”的两行文字,并填入2.1 获取SDK Demo压缩包、License文件、License下载链接获得的License下载链接和License更新提前的天数。 备注:若不使用License的动态更新机制,请参看下面的4部分。

    online版Demo中如下 LFConfig.java文件

    相比offline版本,需要多处理APP_ID、APP_SECRET, 此处将2.2 获取APP_KEY, APP_SECRET得到的APP_KEY、 APP_SECRET的值填入即可。

  3. 然后在app/build.gradle中applicationId的值修改成License绑定的包名。

  4. 不使用License动态更新机制的处理:

    忽略LFConfig.java文件中LICENSE_INFO_URL、DAYS_BEFORE_LIC_EXPIRED值的填写,仅需要注释掉”注意“的文字说明。

    注释掉LFMainActivity.java中对initSDK()方法中关于动态更新License的调用。代码注释后如下:

    private void initSDK() {
        //初始化OCR SDK的License路径
        final String licPath = File.separator + LICENSE_MIDDLE_PATH + File.separator + CardRecognizer.LICENSE_NAME;
        LFBankCardScan.getInstance().initLicensePath(this, licPath, CardRecognizer.LICENSE_NAME);
//        try {
//            //获取剩余天数
//            int remainingDays = LFBankCardScan.getInstance().getRemainingDays(this);
//            //License不在有效期内或到了更新的时间,则启动下载
//            if (!LFBankCardScan.getInstance().checkLicenseValid(this) || remainingDays < DAYS_BEFORE_LIC_EXPIRED) {
//                LFLicDownloadManager.getInstance().downLoadLic(this, LICENSE_INFO_URL, LFBankCardScan.getInstance().getLicPath(),
//                        new LFLicDownloadManager.DownloadListener() {
//                            @Override
//                            public void onDownload(boolean isSuccess, String errorMsg) {
//                                //下载完成的回调可写在这里
//
//                            }
//                        });
//            }
//        } catch (IllegalArgumentException e) {
//            LFLog.e(TAG, e.getMessage());
//            e.printStackTrace();
//        } catch (Exception e) {
//            LFLog.e(TAG, e.getMessage());
//            Toast.makeText(LFMainActivity.this, e.getMessage(), Toast.LENGTH_LONG).show();
//            e.printStackTrace();
//        }
    }

完成以上步骤,即可运行体验Demo功能了。

4. 集成指南

如果集成过程中碰到错误或问题,请按如下步骤尝试解决:
  1. 先查看Android Studio打出的log信息尝试解决;
  2. 参考《常见问题》部分解决;
  3. 利用搜索引擎搜索遇到的问题,尝试解决;
  4. 联系Linkface售后,协助解决。

4.1 将SDK集成到工程

4.1.1 集成方式一:将UI层(LFOCRUILib)作为一个工程依赖(Demo工程使用此方式)

  1. 假如您开发的工程名为MyOCRProject,用Android Studio打开该工程。目录结构如下: 项目结构

    然后将LFOCRUILib整个工程拷贝到MyOCRProject工程的同级目录下,如图:目录

  2. 在工程MyOCRProject的根目录下的settings.gradle文件中加入

    includeFlat 'LFOCRUILib'
    include ':LFOCRUILib:LFCard'
    

    最终settings.gradle如图:

    settings

  3. 添加依赖

    在工程MyOCRProject的app/builde.gradle下添加

    repositories {
     flatDir {
         dirs '../../LFOCRUILib/LFCard/libs'
     }
    }
    

    在dependencies{}中添加

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

    最终,build.gradle中有

    repositories {
     flatDir {
         dirs '../../LFOCRUILib/LFCard/libs'
     }
    }
    dependencies {
       compile project(path: ':LFOCRUILib:LFCard')
    }
    

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

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

权限说明:

名称 用途
CAMERA 调用相机进行扫描或拍照
VIBRATE 调用手机震动器再识别成功时发出震动
WRITE_EXTERNAL_STORAGE 拍摄照片时的临时存储
INTERNET 访问网络权限,用于online版本解密识别结果或License下载时
ACCESS_NETWORK_STATE 获取网络状态

5.动态申请系统权限。Android6.0之后需要动态申请权限。在相应权限使用之前,请添加相应权限的申请。此处给出CAMERA权限的判断和动态申请示例:

/**
     * 判断是否有权限,没有就去请求
     *
     * @param permissionRequestCode
     * @return
     */
    private boolean isHavePermission(int permissionRequestCode) {
        boolean isHave = true;
        if (isMarshmallow()) {

            if (checkSelfPermission(Manifest.permission.CAMERA) != PackageManager.PERMISSION_GRANTED) {
                // Permission has not been granted and must be
                // requested.

                if (shouldShowRequestPermissionRationale(Manifest.permission.CAMERA)) {
                    // Provide an additional rationale to the user if
                    // the permission was not granted
                    // and the user would benefit from additional
                    // context for the use of the permission.
                }
                // Request the permission. The result will be received
                // in onRequestPermissionResult()
                isHave = false;
                requestPermissions(
                        new String[]{Manifest.permission.CAMERA},
                        permissionRequestCode);
            } else {
                // Permission is already available, start camera preview
                isHave = true;
            }
        } else {
            isHave = true;
        }
        return isHave;
    }

   private static boolean isMarshmallow() {
        return Build.VERSION.SDK_INT >= 23;
    }

    /**
     * 请求权限返回
     *
     * @param requestCode
     * @param permissions
     * @param grantResults
     */
    public void onRequestPermissionsResult(int requestCode,
                                           String[] permissions, int[] grantResults) {
        if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            //申请权限成功,跳到扫描界面
            toScanActivity(requestCode);
        } else {
            showToast(LFConstants.ERROR_CAMERA_REFUSE);
        }
    }

其他权限原理相同,可自行修改添加。详细可参考Demo代码。

6.拷贝License文件。在您app的module下src/main目录下创建assets目录,将License文件LinkfaceID.lic拷贝粘贴在assets目录下。

7.初始化SDK的License路径。在APP启动时,进行SDK的License路径初始化。如在MainActivity的onCreate方法中,示例代码如下:

//初始化OCR SDK的License路径
        final String licPath = File.separator + "ocr" + File.separator + CardRecognizer.LICENSE_NAME;
        LFIDCardScan.getInstance().initLicensePath(this, licPath, CardRecognizer.LICENSE_NAME);

此示例为身份证识别SDK,银行卡识别的同理。

8.此时可以跳转扫描界面。可参考Demo中LFMainActivity.java中的代码。跳转方式,以及数据获取方式参考身份证接口调用流程银行卡接口调用流程

4.1.2 集成方式二:将UI层(module:LFCard)作为一个module导入

  1. 假如您开发的工程名为MyOCRProject,Android Studio打开该工程。然后点击File->New->Import Module,选择压缩包根录下LFOCRUILib工程中的LFCard模块,点击Finish完成导入。
  2. 添加依赖,在MyOCRProject的app/builde.gradle下添加

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

    在dependencies{}中添加

     compile project(':LFCard')
    

最终,build.gradle中有

    repositories {
     flatDir {
        dirs '../LFCard/libs'
        }
    }
    dependencies {
      compile project(':LFCard')
    }

后续步骤与第一种集成步骤的4-8相同。点此跳转。

4.1.3 集成方式三: 将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 引入到工程中。如在Android Studio中,将jar文件拷贝 app/libs 目录下,在builde.gradle添加依赖。注:可重命名该文件。

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

至此,可以使用OCR SDK的识别功能了。
开发者需重点关注银行卡识别和身份证识别的API:
银行卡识别:LFBankCardScan
身份证识别:LFIDCardScan

银行卡识别LFBankCardScan的使用步骤:(身份证识别同理)

  1. 调用initLicensePath初始化License的路径;
  2. 调用initBankCardScan初始化识别模型;
  3. 调用scanBankCard进行银行卡识别(可多次调用);
  4. 使用识别功能结束,调用releaseIDCardScan释放识别模型。

开发者可根据OCR SDK提供的识别功能自行开发UI等相关功能。可参考LFOCRUILib下的module:LFCard。

4.2 SDK初始化说明

旧版本(<版本5.5)

在扫描识别前,初始化SDK识别模型。如在识别界面IDCardActivity的onCreate()方法中调用:

LFIDCardScan.getInstance().initIDCardScan(getContext(), licenseName);

并处理可能抛出的异常。可用try...catch...语句包裹。

新版本(>=版本5.5)

1.在app启动时,完成SDK的License初始化。如在您的MainActivity的onCreate()中。并可以完成License的有效期判断及动态更新。代码如下:

private void initSDK() {
        //初始化OCR SDK的License路径
        final String licPath = File.separator + LICENSE_MIDDLE_PATH + File.separator + CardRecognizer.LICENSE_NAME;
        LFIDCardScan.getInstance().initLicensePath(this, licPath, CardRecognizer.LICENSE_NAME);

        try {
            //获取剩余天数
            int remainingDays = LFIDCardScan.getInstance().getRemainingDays(this);
            //License不在有效期内或到了更新的时间,则启动下载
            if (!LFIDCardScan.getInstance().checkLicenseValid(this) || remainingDays < DAYS_BEFORE_LIC_EXPIRED) {
                LFLicDownloadManager.getInstance().downLoadLic(this, LICENSE_INFO_URL, LFIDCardScan.getInstance().getLicPath(),
                        new LFLicDownloadManager.DownloadListener() {
                            @Override
                            public void onDownload(boolean isSuccess, String errorMsg) {
                                //下载完成的回调可写在这里

                            }
                        });
            }
        } catch (IllegalArgumentException e) {
            LFLog.e(TAG, e.getMessage());
            e.printStackTrace();
        } catch (Exception e) {
            LFLog.e(TAG, e.getMessage());
            Toast.makeText(LFMainActivity.this, e.getMessage(), Toast.LENGTH_LONG).show();
            e.printStackTrace();
        }
    }

License路径初始化的API:

public void initLicensePath(Context context, String licensePathAndName, String licenseAssetsName)
此处License的加载流程图:

License加载流程图

备注:此处licensePathAndName路径下的License为下载的License。若下载失败,则读取该License失败,SDK会再去读取assets下默认的License文件。故建议开发者在开发时assets下依然存放License。避免因下载License失败而导致SDK无法正常运行。

2.在扫描识别前,初始化识别模型,如在识别界面IDCardActivity的onCreate中调用:

int modelRet = LFIDCardScan.getInstance().initIDCardScan(getContext());

初始化完成后即可使用OCR识别功能了。详细使用说明请参考身份证接口调用流程银行卡接口调用流程

4.3 获取数据

  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) {
                     showToast("解析数据失败");
                     finish();
                 }
             });
         } else {
             showToast("解析数据失败");
             finish();
         }
    

4.4 解决代码混淆

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

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

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

5. 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的内容

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

6.1 说明

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

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

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

  • 注:将SDK集成完成,即可按此步骤使用银行卡SDK,身份证扫描SDK同理。
  • 6.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。

    6.2.2 获取License剩余有效天数

    返回license剩余有效天数

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

    6.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);
    }
    

    6.3 License下载说明

    6.3.1 获取下载License信息的链接

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

    6.3.2 License下载时序图

    时序图

    6.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" }

    6.3.4 License下载原理

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

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

    6.4.1 多个SDK使用同一License

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

    6.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);
    
    6.4.1.2 动态更新下载时,仅需要使用活体SDK或OCR SDK的一个SDK中判断License有效期并使用LFLicDownloadManager下载。

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

    6.4.2 多个SDK使用不同License

    6.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);
    
    6.4.2.2 License动态更新

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

    results matching ""

      No results matching ""