更新记录

1.5.0(2020-03-26)

更新Android的normal库版本到4.0.10

1.4.0(2020-03-23)

iOS SDK 升级到最新版本 3.3.1

查看更多

原生插件通用使用流程:

  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 的时候,传递参数的数据流向画一个草图,如下所示。

[图片] /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 回传NSStringNSDictionary 类型的参数。

由于 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":"左上角返回键:用户授权中取消"
        }
    }
}

隐私、权限声明

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

"NSPhotoLibraryUsageDescription", "NSPhotoLibraryAddUsageDescription", "NSCameraUsageDescription"

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

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

许可协议

作者未提供license.md

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问