更新记录

2.2.0（2023-04-18）

1. 优化识别体验
2. 去掉 license 校验字段

2.1.0（2023-04-17）

1. 兼容 iPhone14pro + 设备对焦问题
2. 优化识别体验

2.0.1（2022-09-21）

bugfix：修复 license 校验失败返回错误码为空的问题

平台兼容性

原生插件通用使用流程：

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

付费原生插件目前不支持离线打包。
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 的时候，传递参数的数据流向画一个草图.

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

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

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

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

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

WX_EXPORT_METHOD(@selector(loginInLiveCheckAndCompareWithIdImageService:callback:))

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

其中，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. 插件接口清单

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

WX_EXPORT_METHOD(@selector(startOCRService:callback:))

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

插件调用接口

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

WX_EXPORT_METHOD(@selector(startOCRService:callback:))

uni-app 中调用示例：

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

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

插件回调接口

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

• startSucceed 回调
• 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
    }
}