更新记录

1.6.1（2022-04-07）下载此版本

优化证件识别体验，识别更快更准确

1.6.0（2022-04-06）下载此版本

更新android版本OCR

1.5.0（2020-03-26）下载此版本

更新Android的normal库版本到4.0.10

平台兼容性

Android	Android CPU类型	iOS
适用版本区间：4.4 - 11.0	armeabi-v7a：支持，arm64-v8a：支持，x86：未测试	适用版本区间：9 - 15

原生插件通用使用流程：

购买插件，选择该插件绑定的项目。
在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

[TOC]

KYC SDK uni-app 插件说明文档

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、H5、以及各种小程序（微信/支付宝/百度/头条/QQ/钉钉）等多个平台。

uni-app 插件 是提供给 uni-app 调用的 native 功能模块，uni-app 提供了插件市场和一套插件规范，我们需要按照规范开发插件，并放在插件市场，uni-app 开发者才能调用。

从技术角度来说，uni-app 插件 就是架在在 native SDK代码和 uni-app 代码之间的一个中间层，负责 uni-app 和 native SDK 通信。

既然是负责通信，数据就要有如下两个基本的流向：

将 uni-app 的参数传给 native SDK，调用 KYC SDK
将 KYC SDK 执行结果返回给 uni-app

1. uni-app 传递参数给插件

uni-app 是一个面向前端的框架，开发语言主要是 vue.js ，在 uni-app 框架中内置了 weex 框架，用来和 native SDK 进行交互。

uni-app 在调用 native SDK 的时候，传递参数的数据流向画一个草图，如下所示。

[图片] /storage/img/fde9c411c45e4a6786bf462babf0e1481y4amtq4 /storage/img/d30dda81d8a44aaf8ee948e3729a3959zdh50f6n

由于跨语言和框架，参数只能按照指定格式进行传递。

在 uni-app 侧，参数以 json 格式传递给 native SDK，插件接收到的参数的格式是 NSDictionary ，但是 SDK 需要的参数往往不是 NSDictionary，所以插件需要将 NSDictionary 类型的参数解析出来，再传递给 SDK。

下面，以一个刷脸接口来说明，uni-app 如何将参数传递到 SDK 的，这里我们只关注前面的参数，不关注两个负责回调的 block 参数。

-(void)loginInLiveCheckAndCompareWithIdImageService:(NSString *)userid
                                              nonce:(NSString *)nonce
                                               sign:(NSString *)sign
                                              appid:(NSString *)appid
                                            orderNo:(NSString *)orderNo
                                        apiVersion:(NSString *)apiVersion
                                            licence:(NSString *)licence
                                           faceType:(WBFaceVerifyLivingType)facetype
                                             faceId:(NSString *)faceId
                                          sdkConfig:(WBFaceVerifySDKConfig *)sdkConfig
                                            success:(void (^)())success
                                            failure:(void (^)(WBFaceError *error))failure;

1.1 uni-app 插件提供的接口样式

在 uni-app 插件中，支持“两段式”的接口，一个传入参数 和 一个 callback 参数。

KYC SDK 插件命名规则：保持插件接口名称和 SDK 提供的接口尽可能一致，或者说语义上一致。

比如，上面所示的接口，插件中的接口签名如下：

WX_EXPORT_METHOD(@selector(startWbFaceVerifyService:callback:))

- (void)startWbFaceVerifyService:(NSDictionary *)options
                                    callback:(WXModuleCallback)callbackk{
}

其中，option 接收到的就是 uni-app 传入的 json，callback 用来将 SDK 的执行结果回调给 uni-app 。

1.2 确定 json 的 key

在 KYC 插件中，我们约定，native SDK 接口的形参名称作为 json 的 key。

1.3 确定 json 的 value

KYC SDK 接收的参数分类，以及每一类参数的传递格式：

基本数据类型的参数，比如 BOOL、NSInteger 和 NSString ，这类参数原样传递
UIImage* 类型的参数，uni-app 将图片 base64 编码后传递给插件，插件负责转化成 UIImage 实例
自定义的枚举类型，比如 WBFaceVerifyLivingType 类型的参数，在 OC 中，枚举值本质上是一个 int 值，uni-app 传递枚举值给插件即可
自定义的类的实例，比如 WBFaceVerifySDKConfig* 类型的参数，这类参数作为一个 json 对象传递给插件，json 对象的 key 是类的属性名，json 对象的 value 是属性值

综上，在 uni-app 中，调用示例中的接口，传递的参数格式如下：

{
    userid: "test_user_1",
    nonce : "xxxxxx",
    sign : "xxxxxx",
    appid : "xxxxxx",
    orderNo : "xxxxxx",
    apiVersion : "1.0.0",
    licence : "NwKivlx4CuaA0r1Ri/x7VGugcN5bfIUm",
    faceType: 2,
    faceId: "xxxx",
    sdkConfig: {
        windowLevel:1,
        showSuccessPage:true,
        showFailurePage:false,
        recordVideo:true,
        theme:1
    }
}

插件接收到这个 json 对应的 NSDictionary 对象之后，从中解析出 SDK 需要的各个参数，传入 KYC SDK ，从而调起 SDK。

注意：uni-app 在调用插件的时候，json 的 key 要严格按照规范来，否则插件不能解析！！！

2. 插件将 SDK 执行结果回传给 uni-app

2.1 插件回调接口的样式

按照 1.1 节所讲，插件回调的格式也比较死板，只能通过 callback 这个 block。

我们先看看 WXModuleCallback 定义。

/**
 * @abstract the module callback , result can be string or dictionary.
 * @discussion callback data to js, the id of callback function will be removed to save memory.
 */
typedef void (^WXModuleCallback)(id result);

从注释中可以看出，我们只能通过 callback 接口，给 uni-app 回传NSString 或 NSDictionary 类型的参数。

由于 NSString 类型表达的语义，没有 NSDictionary 丰富，KYC SDK 插件使用 NSDictionary 格式回调。

2.2 `NSDictionary` 格式的确定

以上一节的接口为例来讲，在 SDK 的接口中，有两个 block ，分别表示 login success 和 login failure。

但是在插件的回调中，只有一个 block ，而且 block 中只能传递一个 NSDictionary 参数，所以我们需要制定一套规则。

NSDictionary 参数有四个 key-value 组成：

scene，表示场景，用来确定标记是 SDK 的哪个回调
res，表示具体的回调信息，比如刷脸结果，或者异常的详细信息，这个是可选的

比如，在上面的示例中，success block 回调给外部的格式如下（由于SDK中 success block 没参数，所以就没有 res 这个 key）：

NSDictionary *result = @{
    @"scene":@"login_callback_success",
};

failure block 回调给外部的格式如下：

NSDictionary *result = @{
    @"scene":@"login_callback_failure",
    @"res":@{
            @"code":@(error.code),
            @"desc":error.desc,
            @"domain":error.domain,
            @"reason":error.reason
    },
};

下面会列出 KYC SDK 的所有接口的回调样式。

3. 插件接口清单

本文档只介绍插件的使用，具体参数含义，请参考 KYC 接入文档。

3.1 OCR SDK

uni-app 插件名称：DC-WBOCRService，插件地址。

OCR 插件对外提供一个调用接口。

WX_EXPORT_METHOD(@selector(startOCR:callback:))

下面详细介绍接口调用以及回调方式。

插件调用接口

iOS native SDK 提供的接口如下：

/**
 * @brief 调起SDK入口方法

 * @param config            配置参数
 * @param version           openAPI接口版本号,由腾讯服务统一分配
 * @param appId             appId，由腾讯服务分配的
 * @param nonce             每次请求需要的一次性nonce，一次有效
 * @param userId            每个用户唯一的标识
 * @param sign              签名信息，有接入方后台提供，一次有效
 * @param orderNo           订单号，长度不能超过32位的字符串
 * @param startSucceed      SDK启动成功回调
 * @param recognizeSucceed  识别成功回调，即将退出SDK
 * @param failed            SDK发生异常退出后回调，即将退出SDK
 *
 */
- (void)startOCRServiceWithConfig:(nullable WBOCRConfig *)config
                          version:(nonnull NSString *)version
                            appId:(nonnull NSString *)appId
                            nonce:(nonnull NSString *)nonce
                           userId:(nonnull NSString *)userId
                             sign:(nonnull NSString *)sign
                          orderNo:(nonnull NSString *)orderNo
                     startSucceed:(nonnull WBOCRServiceStartSucceedBlock)startSucceed
                 recognizeSucceed:(nonnull WBOCRServiceRecognizeSuccessBlock)recognizeSucceed
                           failed:(nonnull WBOCRServiceFailedBlock)failed;

uni-app 插件提供的接口方法如下：

WX_EXPORT_METHOD(@selector(startOCR:callback:))

uni-app 中调用示例：

const ocr  = uni.requireNativePlugin('DC-WBOCRService');
ocr.startOCR({
  version : "1.0.0",
  appId :  "xxxxxx",
  nonce :  "xxxxxx",
  userId :  "xxxxxx",
  sign :  "xxxxxx",
  orderNo :  "xxxxxx",
  config: {
    "SDKType": 2,
  }
}, result => {
  console.log("【uni log】startOCR callback ================> result.");
  console.log(result);
  this.result = result.toString();
});

其中，startOCR 后面传入调起 SDK 的参数，result 后面是插件的回调结果。

插件回调接口

回调信息以 json 格式返回给 uni-app，SDK 有以下两种情况的回调：

recognizeSucceed 回调
failed 回调

如上 2.2 节所说，通过 scene 字段来区分回调。

startSucceed 回调表示 SDK 启动成功，使用场景号 login_callback_success 来标记，uni-app 收到的回调结果如下：

{
    "scene":"login_callback_success"
}

recognizeSucceed 回调表示 SDK 识别成功，使用场景号 recognize_callback_success 来标记，识别结果在 res 对应的 value 中，如下示例是身份证国徽面的识别结果，uni-app 收到的回调结果如下：

{
    "scene":"recognize_callback_success"
  "res": {
        "backWarning": "00010000",
        "validDate": "20170119-20270119",
        "authority": "深圳市公安局南山分局",
        "backMultiWarning": "00010000",
        "backClarity": "34",
        "orderNo": "JPynZUmba",
        "backFullImg": "image-base64",
        "sign": "4079DFA895C131BC4B214C5E921DBEFAAEE32665"
    },
}

其它类型卡片识别结果，参考 KYC 文档。

failed 回调表示 SDK 识别异常，使用场景号 callback_failure 来标记，res 中表示错误码和错误描述。

{
    "scene":"callback_failure"
    "res": {
        "desc": "用户取消操作",
        "code": 200101
    }
}

3.2 刷脸 SDK

刷脸 SDK 接口调用和回调与 OCR SDK 类似，刷脸 SDK 。

uni-app 插件名称：DC-WBFaceService，插件地址。

插件 SDK 提供如下入口方法：

WX_EXPORT_METHOD(@selector(startWbFaceVerifyService:callback:))

下面以startWbFaceVerifyService:callback: 为例来讲插件的调用。

插件调用接口

uni-app 插件提供的接口方法如下：

WX_EXPORT_METHOD(@selector(startWbFaceVerifyService:callback:))

uni-app 中调用示例：

const face = uni.requireNativePlugin('DC-WBFaceService');
face.startWbFaceVerifyService({
  userId: "test_user_1",
  nonce : "xxxxxx",
  sign : "xxxxxx",
  appId : "xxxxxx",
  orderNo : "xxxxxx",
  apiVersion : "1.0.0",
  licence : "xxxxxx",
  faceType: "1",
  compareType:"0",
  faceId: "xxxx",
  sdkConfig: {
    //Android和iOS共有的配置参数                                  
    showSuccessPage: true, //是否展示成功页面
    showFailurePage: true, //是否展示失败页面
    recordVideo: false, //是否录制视频
    playVoice: true, //是否播放语音提示
    detectCloseEyes: false, //是否检测用户闭眼
    theme: '0', //sdk皮肤设置，0黑色，1白色

   //android独有的配置参数
   isEnableLog: true, //是否打开刷脸native日志，请release版本关闭！！！

   //iOS独有的配置参数
   windowLevel: '1', //sdk中拉起人脸活体识别界面中使用UIWindow时的windowLevel配置
   manualCookie: true //是否由SDK内部处理sdk网络请求的cookie
  }
}, result => {
  console.log("【uni log】face SDK callback ================> result.");
  console.log(result);
});

其中，startWbFaceVerifyService 后面传入调起 SDK 的参数，result 后面是插件的回调结果。

插件回调接口

回调信息以 json 格式返回给 uni-app，如上 2.2 节所说，通过 scene 字段来对应登录失败和返回人脸认证结果两个回调方法：

wb_face_callback_login_failure
wb_face_callback_verify_result

和 OCR 插件一样，通过 scene 获取具体场景之后，在 res 字段里面读取相应的业务信息，res 是可选的。刷脸成功样例：

{
    "scene":"wb_face_callback_verify_result",
    "res":
    {
        "liveRate":"99",
        "orderNo":"fIABR8jeM",
        "sign":"0F2992AE7ADF69155FF117005BDB3D289A7B3969",
        "similarity":"100.0",
        "success":true,
        "userImageString":""
    }
}

刷脸失败样例:

{   "scene":"wb_face_callback_verify_result",
    "res":
    {
        "orderNo":"fIABR8jeM",
        "success":false,
        "error":
        {
            "code":"41000",
            "desc":"用户取消",
            "domain":"WBFaceErrorDomainNativeProcess",
            "reason":"左上角返回键：用户授权中取消"
        }
    }
}

DC-WBOCRService OCR

更新记录

1.6.1（2022-04-07）下载此版本

1.6.0（2022-04-06）下载此版本

1.5.0（2020-03-26）下载此版本

平台兼容性

原生插件通用使用流程：

KYC SDK uni-app 插件说明文档

1. uni-app 传递参数给插件

1.1 uni-app 插件提供的接口样式

1.2 确定 json 的 key

1.3 确定 json 的 value

2. 插件将 SDK 执行结果回传给 uni-app

2.1 插件回调接口的样式

2.2 `NSDictionary` 格式的确定

3. 插件接口清单

3.1 OCR SDK

插件调用接口

插件回调接口

3.2 刷脸 SDK

插件调用接口

插件回调接口

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

许可协议

作者未提供license.md

DC-WBFaceService

DC-WBNormal

DC-WBOCRService

DC-WBFaceServiceV2

DC-WBOCRServiceV2

DC-WBOCRService OCR

更新记录

1.6.1（2022-04-07） 下载此版本

1.6.0（2022-04-06） 下载此版本

1.5.0（2020-03-26） 下载此版本

平台兼容性

原生插件通用使用流程：

KYC SDK uni-app 插件说明文档

1. uni-app 传递参数给插件

1.1 uni-app 插件提供的接口样式

1.2 确定 json 的 key

1.3 确定 json 的 value

2. 插件将 SDK 执行结果回传给 uni-app

2.1 插件回调接口的样式

2.2 NSDictionary 格式的确定

3. 插件接口清单

3.1 OCR SDK

插件调用接口

插件回调接口

3.2 刷脸 SDK

插件调用接口

插件回调接口

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

许可协议

作者未提供license.md

DC-WBFaceService

DC-WBNormal

DC-WBOCRService

DC-WBFaceServiceV2

DC-WBOCRServiceV2

Modal title

1.6.1（2022-04-07）下载此版本

1.6.0（2022-04-06）下载此版本

1.5.0（2020-03-26）下载此版本

2.2 `NSDictionary` 格式的确定