# 金融场景 API

# 1. 背景说明

API 列表基础上,FinClip围绕金融特色场景,提供了如下API接口供小程序使用。

需声明的是,使用以下API时,请确保宿主App已经集成对应能力且与FinClip SDK实现联调的第三方功能SDK,否则小程序调用将无法实现相关功能。

具体来说,此类场景包括:

  • 如果App集成了FinClip SDK + 已与FinClip 实现联调的SDK,则此时小程序可以直接调用API,并实现相关功能目标
  • 如果App仅集成了FinClip SDK、未集成与FinClip 联调成功的功能SDK,则此时小程序调用API无响应,但不会影响小程序自身业务
  • 如果App集成了FinClip SDK+未与FinClip 联调的SDK,但宿主App根据API内容实现了自定义注册(iOS自定义注册API | Android自定义注册API),则小程序可调用相关API实现指定功能

综合来说,我们建议:

  • 对于小程序开发者,应直接在业务代码中使用本页所述API;通过规范API调用,可最大化帮助开发者减少定制开发的工作量
  • 对于宿主App,只需根据使用场景集成FinClip SDK + 其他指定功能SDK,正常情况下无需关注自定义注册API;通过本规范,宿主App可最大化减少集成、开发、联调工作量
  • 对于第三方功能SDK,可与FinClip联系后,尽快参考本协议、完成双方联调,以便利其他客户接入

# 2. OCR卡片识别(finCardOcr)

接口名称: finCardOcr

接口依赖:无(使用任意版本FinClip SDK 均可调用)

# 请求参数

名称 类型 默认值 说明
type String 非空 "BankCard":银行卡识别
"IDCard":身份证识别
"IDCardCheck":身份证照片质检
"BusiCert":企业营业执照识别
imagePath String 照片文件所在路径
小程序通过chooseImage提取该字段即可
IOS/Android则传递文件绝对路径
其中IOS可将UIImage文件写入临时文件简单解决文件访问问题

# 返回结果

名称 类型 默认值 说明
type String 非空 "BankCard":银行卡识别
"IDCard":身份证识别
"IDCardCheck":身份证照片质检
"BusiCert":企业营业执照识别
errorCode Int 0 识别结果,0表示成功
description String 识别结果描述
recogResult Object 识别结果{"cardNo":卡号,......}

recogResult字段说明

身份证正面

名称 说明
face 0:正面, 1:反面
nation 民族(仅正面有)
gender 性别(仅正面有)
birthday 生日(仅正面有)
address 地址(仅正面有)
name 姓名(仅正面有)
idNo 身份证号码(仅正面有)
startDate 有效期起始日期(仅反面有)
endDate 有效期截止日期(仅反面有)
signOrg 签发机关(仅反面有)

身份证质检

名称 说明
risk 图片风险:
0=无
1=复印件
2=拍屏
3=假证件
4=有水印
5=遮挡
6=切边
7=卡变形
8=有光斑

银行卡

名称 说明
cardNo 卡号
bankName 银行
bankId 银行标识id
cardType 卡类型:借记卡 准贷记卡

营业执照

名称 说明
regOrg 登记机关
busiScrope 经营范围
certNo 统一社会信用代码/营业执照号
regDate 登记日期
capital 注册资本
address 住所
expDate 营业期限
represent 法人代表
certType 营业执照类型:正本、副本
corpName 企业名称
corpType 企业类型
foundDate 成立日期

# 3. 人脸联网身份核验(finFaceAuth)

接口名称: finFaceAuth

接口依赖:无(使用任意版本FinClip SDK 均可调用)

# 请求参数

名称 类型 默认值 说明
idNo String 身份证号码
name String 姓名
imagePath String 照片文件所在路径

# 返回结果

名称 类型 默认值 说明
errorCode Int 0 识别结果,0表示成功
description String 识别结果描述
score double 0-1 相似度

# 4. 活体检测(finLivenessCheck)

接口名称: finLivenessCheck

接口依赖:无(使用任意版本FinClip SDK 均可调用)

# 请求参数

名称 类型 默认值 说明

# 返回结果

名称 类型 默认值 说明
resultType String "success" 成功、"back"用户点击返回取消活体检测
faceImgStr String 活体检测返回图片,Base64后的byte数组。仅成功返回

# 5. 打开三方app(finOpenOtherApp)

接口名称: finOpenOtherApp

接口依赖:无(使用任意版本FinClip SDK 均可调用)

# 请求参数

名称 类型 默认值 说明
package String App包名,Android用于判断App是否已安装,仅Android
url String App的scheme加url,iOS用于判断App是否已安装且跳转用;Android用于跳转用
downloadUrl String 下载App地址
alertMsg String 下载提示框提示语,如不传则不弹提示框直接跳转页面

# 6. 双向视频认证(finOpenWitnessVideo)

接口名称:finOpenWitnessVideo

接口依赖:无(使用任意版本FinClip SDK 均可调用)

# 请求参数

名称 类型 默认值 说明
videoType String 视频服务类型
videoIp String 视频服务ip
videoPort String 视频服务端口
loginName String 登录名
loginPwd String 登录密码(可选)
roomId String 房间id
roomName String 房间名
roomPwd String 房间密码(可选)
appId String anychat集群appId

# 返回结果

名称 类型 默认值 说明
videoFlag String 非空 返回标志 0,成功,1,失败,2,驳回
rejectReason String 驳回理由
message String 详细信息

# 7. 单向视频录制小程序实现

接口依赖:本组件无需依赖 FinClip SDK 以外的第三方 SDK

小程序单向录制组件使用

1、下载录制视频组件实例代码包

录制 demo v1.0.0 (opens new window)

组件代码在根目录的 components 内,也可直接用 ide 工具打开录制 demo 查看效果

2、在需要使用的页面或组件的 json 文件内,引入录制组件

{
  "usingComponents": {
    "video-recognition": "../../components/video-recognition/index"
  }
}

3、在页面或组件的 wxml 内,使用组件

<view style="width: 100vw;height: 100vh;">
  <video-recognition recordTime="{{recordTime}}"
                     top="{{top}}"
                     stepList="{{stepList}}"
                     buttonStyle="{{buttonStyle}}"
                     mask="../../assets/img_mask_person@3x.png"
                     resolution="low"
                     bind:onRecordReady="onRecordReady"
                     bind:onRecordStart="onRecordStart"
                     bind:onRecordEnd="onRecordEnd"
                     bind:onRecordError="onRecordError">
  </video-recognition>
</view>

注意

录制组件外层需要声明宽高尺寸,录制组件内会按 width: 100%; height: 100% 展示

4、组件参数一览

名称 类型 是否必须 默认值 备注
resolution String medium 分辨率,可选值:low、medium、high 只在初始化时有效,不能动态变更
mask String - 取景区域的遮罩资源路径,建议使用小程序内资源的相对路径,https 地址会有加载耗时,遮罩会按 width 100% height 100% 的尺寸放在 camera 上,注意和组件尺寸相匹配
recordTime Number 30000 录制时间,单位为毫秒
top Number 20 单位 rpx 文本提示距顶部的距离,也可修改 video-recognition 组件内的 wxss,自定义文本的position
stepList Array<Object> - 每⼀步的语⾳和提示⽂案配置,最大支持长度为 3,数据元素结构可参考表格后的说明
buttonStyle Object - 控制录制按钮的样式,可对按钮进行位置上的微调,目前支持以下字段:width、height、left、top、bottom、right,只在初始化时有效,不能动态变更
onRecordReady EventHandler - 通过 onRecordReady 绑定,ready 前会进行一些异步资源的下载,资源准备好后触发,可用于在使用组件的 page 页面判断录制组件是否准备完毕,从而控制 loading 和组件展示
onRecordStart EventHandler - 通过 bind:onRecordStart 绑定,录制开始时触发
onRecordEnd EventHandler - 通过 bind:onRecordEnd 绑定,录制结束时触发,回调方法参数 res,res.tempVideoPath 即为录制视频的本地文件地址
onRecordError EventHandler - 通过 bind:onRecordError 绑定,录制报错时触发,回调方法参数 res,res.errMsg 为发生错误时的报错信息

stepList 参数说明

每⼀步的语⾳和提示⽂案配置,最大支持长度为 3

数据元素结构如下:

{
  "audioSrc": "https://xxxxx.mp3",
  "showTime": 0,
  "textList": []
}

audioSrc - 音频链接,建议使用 https 链接,组件 attached 会下载音频资源,若下载失败会执行 error 回调,报资源加错错误

注意

mp3 的域名需在管理后台添加到白名单内,否则会下载失败

showTime - 文本提示和音频的展示时间,毫秒数,0 表示初始展示,2000 表示录制开始 2s 时展示

textList - 文本提示,数组类型

textList 参数对象如下:

{
  "text": '请用普通话大声朗读'
}

text - 文本内容

可添加 width|height|padding|margin|color|fontSize|fontWeight|textAlign 等样式属性简单控制文本样式:

{
  "text": '文本',
  "color": 'red',
  "fontWeight": 'bold',
  "margin": '0 20rpx'
}

注意

一个 textList 子元素,展示时会以单行不换行展示,可按需拆分成多行多个子元素

另外,如果单行内容内需要个别词语高亮展示,text 属性可以传入数组,属性与上述对象参数一致,如下:

{
  "text": [{
    "text": '文本'
  }, {
    "text": '高亮文本',
    "color": 'red',
    "fontWeight": 'bold',
    "margin": '0 20rpx'
  }, {
    "text": '文本'
  }]
}

stepList 只在初始化时有效,不能动态变更

本组件使用小程序原生语法开发,除文档描述的参数外,也可自行修改组件内的逻辑,满足不同的业务需求。

# 8. webRTC 功能小程序实现

接口依赖:需基础库及 SDK 支持

为了支持小程序中使用 webRTC 功能,SDK 通过集成 GoogleWebRTC 库,由原生提供 webRTC 相关 API 给到基础库,并提供相关 API 给小程序使用

尽可能地保留了 webRTC 相关的 API 形式,减少 H5 迁移到小程序的成本

新增的小程序 API 如下:

# MediaDevice

ft.webrtc.mediaDevices.enumerateDevices()

获取 webRTC 可用的音视频硬件信息,执行后返回一个 Promise 对象。

Promise 返回值

属性 类型 说明
devicesList Array 包含设备信息对象的数组

示例代码

const devicesList = await ft.webrtc.mediaDevices.enumerateDevices()
// or
ft.webrtc.mediaDevices.enumerateDevices().then(devicesList => {
  console.log(devicesList)
})

ft.webrtc.mediaDevices.getSupportedConstraints()

获取当前设备所支持的约束属性(如帧率,窗口大小),执行后返回一个 Promise 对象。

Promise 返回值

属性 类型 说明
info Object 包含当前设备属性的一个对象

示例代码

const info = await ft.webrtc.mediaDevices.getSupportedConstraints()
// or
ft.webrtc.mediaDevices.getSupportedConstraints().then(info => {
  console.log(info)
})

MediaStream.getUserMedia(Object object)

向用户申请媒体输入,执行后返回一个 Promise 对象,Promise 最后会返回一个 Object 对象。

注意

在移动端中,getUserMedia 会有调用限制,如果 getUserMedia 获取到 stream,且 webRTC 处于连接中,再次调用 getUserMedia 可能会抛错。建议业务上避免重复调用的逻辑。

参数

Object object

属性 类型 默认值 必填 说明
video boolean 是否获取视频流
audio boolean 是否获取音频流

Promise 返回值

属性 类型 说明
stream Object 常规媒体流无法传输到小程序,这里的 stream 仅是一个简单封装对象,仅包含一个 streamId 和 getTracks 方法

示例代码

const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true, video: true })
// or
ft.webrtc.mediaDevices.mediaDevices().then(stream => {
  console.log(stream)
  console.log(stream.streamId)
})

stream.streamId

字符串

将 streamId 传给 webrtcVideo 组件,即可播放该 stream 流,具体可参考 webrtcVideo 组件文档。

stream.getTracks()

获取 stream 流的 tracks 数组,执行后返回一个 Promise 对象,Promise 最后会返回一个 tracks 数组。

Promise 返回值

属性 类型 说明
tracks Array 获取到 stream tracks 数组,一般包含 video track 和 audio track

示例代码

const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true, video: true })
const tracks = await stream.getTracks()
tracks.forEach((track) => {
  console.log(track)
})

track.stop()

关闭 track,可用于停止 stream 流的场景。

示例代码

const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true, video: true })
const tracks = await stream.getTracks()
tracks.forEach((track) => {
  track.stop()
})

# RTCPeerConnection

ft.webrtc.createRTCPeerConnection(Object options)

创建 rtc connection 实例,执行后返回 Promise,Promise 最后返回实例对象。

Object options

参数均透传给 createRTCPeerConnection

具体 options 参数可参阅 webRTC 标准文档 (opens new window)

示例代码

const options = { iceServers: [{ urls: "stun:stun.stunprotocol.org" }] }
const pc = await ft.webrtc.createRTCPeerConnection(options)

RTCPeerConnection 属性

当前已支持的 RTCPeerConnection 属性

属性 说明
canTrickleIceCandidates
conectionState
currentLocalDescription
currentRemoteDescription
iceConnectionState
iceGatheringState
localDescription
peerIdentity
remoteDescription
signalingState

示例代码

const options = { iceServers: [{ urls: "stun:stun.stunprotocol.org" }] }
const pc = await ft.webrtc.createRTCPeerConnection(options)

console.log(pc.canTrickleIceCandidates)
console.log(pc.currentLocalDescription)
console.log(pc.currentRemoteDescription)
console.log(pc.peerIdentity)

RTCPeerConnection 事件监听

当前已支持的 RTCPeerConnection 事件

属性 event 说明
icecandidate { candidate: { ... }} 触发时返回 icecandidate 信息,仅包含 candidate 字段数据
iceconnectionstatechange { iceConnectionState, timeStamp }
negotiationneeded
signalingstatechange { signalingState }
track { streams } streams 的数组项对象是包含一个 streamId 的 object

示例代码

const options = { iceServers: [{ urls: "stun:stun.stunprotocol.org" }] }
const pc = await ft.webrtc.createRTCPeerConnection(options)

pc.addEventListener('icecandidate', event => {
  console.log(event.candidate)
  console.log(event.candidate.address)
  console.log(event.candidate.type)
  console.log(event.candidate.sdpMLineIndex)
  console.log(event.candidate.sdpMid)
})

pc.addEventListener('iceconnectionstatechange', event => {
  console.log(event.iceConnectionState)
})

pc.addEventListener('negotiationneeded', event => {
  console.log(event)
})

pc.addEventListener('signalingstatechange', event => {
  console.log(event)
})

pc.addEventListener('track', event => {
  console.log(event.streams)
  // 将 streamId 传给 webrtcVideo 组件,即可播放该 stream 流,具体可参考 webrtcVideo 组件文档。 
  this.setData({
    remoteStreamId: e.streams[0].streamId
  })
})

RTCPeerConnection.createOffer(Object object)

创建一个SDP offer,执行后返回一个 Promise 对象,Promise 最后会返回一个 offer Object 对象。

参数

Object object

属性 类型 默认值 必填 说明
iceRestart boolean false
offerToReceiveAudio boolean false
offerToReceiveAudio boolean false
voiceActivityDetection boolean true

Promise 返回值

属性 类型 说明
offer Object 包含 sdp 和 type 两个字段的一个 Object

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(options)
const offer = await pc.createOffer({
  offerToReceiveAudio: true,
  offerToReceiveVideo: true
})
await pc.setLocalDescription(offer)

RTCPeerConnection.createAnswer(Object object)

创建一个SDP answer,执行后返回一个 Promise 对象,Promise 最后会返回一个 answer Object 对象。

参数

Object object

属性 类型 默认值 必填 说明
iceRestart boolean false
offerToReceiveAudio boolean false
offerToReceiveAudio boolean false
voiceActivityDetection boolean true

Promise 返回值

属性 类型 说明
answer Object 包含 sdp 和 type 两个字段的一个 Object

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(options)
const answer = await pc.createAnswer({
  offerToReceiveAudio: true,
  offerToReceiveVideo: true
})

RTCPeerConnection.setLocalDescription(Object object)

设置 offer/answer,执行后返回一个 Promise。

参数

Object object

传入获取到的 offer 或 answer

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(options)
const offer = await pc.createOffer({
  offerToReceiveAudio: true,
  offerToReceiveVideo: true
})
await pc.setLocalDescription(offer)

RTCPeerConnection.setRemoteDescription(Object object)

设置 offer/answer,执行后返回一个 Promise。

参数

Object object

传入获取到的 offer 或 answer

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(options)

// 伪代码,offer 是 remote 端发送过来的
const offer = getFromRemote()
await pc.setRemoteDescription(offer)

const answer = await pc.createAnswer({
  offerToReceiveAudio: true,
  offerToReceiveVideo: true
})
await pc.setLocalDescription(answer)

RTCPeerConnection.addIceCandidate(Object object)

添加 candidate 到 connection 中

参数

Object object

参数需传入 candidate 对象,也就是 icecandidate 事件获取到的 candidate 对象

部分属性在不同端有细微差异,具体以实际获取到的值为准

示例代码

// 伪代码

// A 端
const pcA = await ft.webrtc.createRTCPeerConnection(options)

pcA.addEventListener('icecandidate', event => {
  // 发送给 B 端
  sendToB(event.candidate)
})


// B 端
const pcB = await ft.webrtc.createRTCPeerConnection(options)

const candidate = await getFromA()
await pcB.addIceCandidate(candidate)

RTCPeerConnection.getConfiguration()

获取 connection 的 configuration,执行后返回 Promise。

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(servers, mediaConstraints)
const configuration = await pc.getConfiguration()

RTCPeerConnection.addTrack(Object object)

添加 track 到当前 connection 中,注意接口是异步接口。

参数

Object object

参数需传入 track 对象,track 是 getUserMedia 获取到的 stream 通过 getTracks 获取到的。

示例代码

const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true, video: true })
const pc = await ft.webrtc.createRTCPeerConnection(servers, mediaConstraints)
const tracks = await stream.getTracks()
tracks.forEach(t => {
  pc.addTrack(t)
})

RTCPeerConnection.close()

关闭 connection 连接

示例代码

const pc = await ft.webrtc.createRTCPeerConnection(servers, mediaConstraints)
pc.close()

# webRTC 相关组件

webRTCVideo 组件

用于播放 webrtc 媒体流的组件

属性

属性 类型 默认值 必填 说明
src string 必须是 webrtc:// 这样的格式,streamId 可以通过 getUserMedia 或 connection track 事件获取到
muted boolean false video 是否静音

示例代码

<webrtc-video muted
              src="webrtc://{{localStreamId}}"></webrtc-video>

<webrtc-video src="webrtc://{{remoteStreamId}}"></webrtc-video>
// getUserMedia 获取到本地的流
const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true, video: true })
const { streamId } = stream
this.setData({
  localStreamId: streamId
})


// webrtc connection track 事件获取到的远端视频流
const pc = await ft.webrtc.createRTCPeerConnection()
pc.addEventListener('track', event => {
  const { streams } = event
  this.setData({
    remoteStreamId: streams[0].streamId
  })
})

webRTCAudio 组件

用于播放 webrtc 媒体流的组件,与 webRTCVideo 的区别是只会播放音频。

属性

属性 类型 默认值 必填 说明
src string 必须是 webrtc:// 这样的格式,streamId 可以通过 getUserMedia 或 connection track 事件获取到

示例代码

<webrtc-audio src="webrtc://{{localStreamId}}"></webrtc-audio>

<webrtc-audio src="webrtc://{{remoteStreamId}}"></webrtc-audio>
// getUserMedia 获取到本地的流
const stream = await ft.webrtc.mediaDevices.getUserMedia({ audio: true })
const { streamId } = stream
this.setData({
  localStreamId: streamId
})


// webrtc connection track 事件获取到的远端视频流
const pc = await ft.webrtc.createRTCPeerConnection()
pc.addEventListener('track', event => {
  const { streams } = event
  this.setData({
    remoteStreamId: streams[0].streamId
  })
})
© 2021 凡泰极客
  • 免费试用
  • 编组
  • 编组 2