金融场景 API

请注意

金融场景 API 是在 常见API 列表的基础上，围绕金融特色场景，与小程序生态合作伙伴进行合作，维护的面向金融行业常用的 API 能力。

在使用以下 API 时，请确保宿主 App 已经集成了 第三方 SDK，否则小程序将无法实现相关功能。如果您在使用时有疑惑，请与我们联系。

1. 使用背景

金融场景 API 的使用背景如下：

• 如果 App 集成了 SDK + 实现联调的 SDK，此时小程序可以直接调用 API，并实现相关功能目标；
• 如果 App 仅集成了 SDK，未集成 联调成功的功能 SDK，此时小程序调用金融场景 API 将无响应；
• 如果 App 集成了 SDK + 未联调的 SDK，且宿主 App 根据 API 内容实现了自定义注册（iOS自定义注册API | Android自定义注册API），则小程序可调用相关 API 实现指定功能；

综合来说，我们建议：

• 对于金融行业的小程序开发者，可直接在业务代码中使用本页所述 API，通过规范 API 调用，可最大化帮助开发者减少定制开发的工作量；
• 对于金融行业的宿主 App 厂商，可根据实际需要自行集成 SDK + 其他指定功能 SDK，通过本规范，可最大化减少集成、开发、联调工作量；

合作须知

第三方 SDK 开发厂商可按照统一的开发规范，设计在小程序场景中集成相关功能的具体方式。您可以致电 0755-86967467 或写邮件至 wangzi@finogeeks.com ，了解相关事宜。

2. 身份验证相关 API

2.1 OCR卡片识别（finCardOcr）

接口名称: finCardOcr

接口依赖：无（使用任意版本 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	成立日期

2.2 人脸联网身份核验（finFaceAuth）

接口名称: finFaceAuth

接口依赖：无（使用任意版本 SDK 均可调用）

请求参数

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

返回结果

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

2.3 活体检测（finLivenessCheck）

接口名称: finLivenessCheck

接口依赖：无（使用任意版本 SDK 均可调用）

请求参数

名称	类型	默认值	说明
无

返回结果

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

2.4 打开三方app（finOpenOtherApp）

接口名称: finOpenOtherApp

接口依赖：无（使用任意版本 SDK 均可调用）

请求参数

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

2.5 双向视频认证（finOpenWitnessVideo）

接口名称：finOpenWitnessVideo

接口依赖：无（使用任意版本 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		详细信息

2.6 单向视频录制小程序实现

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

小程序单向录制组件使用

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

录制 demo v1.0.0 (opens new window)

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

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

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

3、在页面或组件的 fxml 内，使用组件

<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 只在初始化时有效，不能动态变更

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

3. WebRTC 相关 API

为了支持小程序中使用 WebRTC 功能， 小程序 SDK 在基础库中原生提供了 WebRTC 相关 API。

为了减少 HTML5 迁移至小程序的成本，我们尽可能地保留了 WebRTC 相关的 API 形式，小程序相关 API 如下：

请注意

本功能基于Google WebRTC 库实现，您需要确认基础库及 SDK 版本支持。

• iOS SDK 集成方式：请看这里
• Android SDK 集成方式：请看这里

3.1 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()
})

3.2 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()

3.3 WebRTC 相关组件

WebRTC Video 组件

用于播放 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
  })
})

WebRTC Audio 组件

用于播放 WebRTC 媒体流的组件，与 WebRTC Video 的区别是只会播放音频。

属性

属性	类型	默认值	必填	说明
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
  })
})