青蛙小程序 - 特殊API接口

...

admin

1.背景

小程序广泛的用于手机微信,为了方便商户在青蛙机具上进行更多的定制化开发,青蛙app目前也初步支持运行小程序。

本文档用于说明,青蛙小程序开发者如何使用青蛙app的特殊小程序API完成商户小程序的开发,更好的完成青蛙上的商户服务小程序。

微信小程序已经具备了很多小程序API 供开发者使用,青蛙小程序源自微信小程序,能够做到开发,API,用户体验和微信小程序基本保持一致。

但是由于微信小程序有部分API高度依赖手机微信的环境,这些API青蛙小程序将无法支持。

后续我们将会给出详细的不可用接口列表,这边对青蛙小程序无法支持的API进行一个大致的说明,他们包括:

  • 强手机相关的API:例如通讯录API,电话API
  • 生物认证相关的API

# 2.青蛙特殊API介绍

小程序开发者,在开发青蛙小程序时,可以使用青蛙app,独立于手机微信小程序API的特殊能力,我们称之为青蛙小程序API。

# 2.1. 青蛙特殊API的类型

青蛙小程序特殊API,从技术角度来讲可以分为两种:

  • AsyncJsApi:商户小程序开发者主动调用,青蛙负责回调通知调用结果,操作流程是异步
  • JsEvent:商户小程序开发者主动监听Event,设置回调,特定Event触发后,商户小程序开发者设置的Event回调会被自动执行,操作流程也是异步

AsyncJsApi范例

wxfaceapp.writeToSerialPort({
  msgToFlush:"msg",
  success(res){
    console.log("success [writeToSerialPort]")
   },
   fail(res){
    console.log("fail [writeToSerialPort]")
    console.log(res.reply)
   }
})

JsEvent范例

wxfaceapp.onRemoteMessage(function (res) {
  console.log("onRemoteMessage retCode = " + res.replyCode)
})

# 2.2. API分类

从业务上来说,我们可以讲青蛙特殊API分为下面几大类别:

  • 基础能力API:提供一些青蛙App特有的基础能力给商户小程序,例如文字转语音播报,查询系统信息,设备信息等
  • 支付相关API:提供青蛙App的刷脸支付相关API给商户小程序,例如刷脸支付,快速支付,查询支付状态等
  • 特殊能力API:提供一些特殊场景下的拓展API给商户小程序,如会员场景下,发送传码,收款指令等

# 2.3. 使用注意事项

第一点:调用时机

青蛙特殊API的本质是小程序Js基础库的"插件",所以在小程序js基础库尚未加载完毕前,调用青蛙特殊API将不会有任何效果.

通俗一点的说法,就是商户小程序开发者,需要在确保page.onLoad这个生命周期函数回调完毕后,调用特殊API.

第二点:与三方框架的兼容问题

目前在开发过程中,发现如果商户小程序开发者使用了一些跨平台开发库的时候,会出现特殊API无法调用的问题,目前我们正在努力解决中.


# 3.基础能力API

# 3.1. 获取系统信息 - checkWxFacePayOsInfo

请注意:此API可能会发生更新,更多的相关信息会被加入

接口限制:无

青蛙小程序可以通过wxfaceapp.checkWxFacePayOsInfo获取青蛙机具,和青蛙app的相关信息。

建议在小程序运行的时候首先调用此函数确认一些必要信息。

当机具和青蛙app处于错误状态,或是小程序环境出现问题时,此函数会进行失败回调。

调用范例如下:

//获取青蛙相关信息
wxfaceapp.checkWxFacePayOsInfo({
  success(res){
    console.log("success [checkWxFacePayOsInfo]")
    console.log(res.osVersion)
    console.log(res.osStatus)
  },
  fail(res){
    console.log("fail [checkWxFacePayOsInfo]")
    console.log(res.osErrorMsg)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
osVersion String 该青蛙机具的Android系统版本
osStatus String 青蛙机具与青蛙app状态,成功回调返回"valid"
osSerialNumber String 该青蛙机具的设备号

失败回调参数如下:

Object res

参数 类型 说明
osErrorMsg String 获取系统信息失败的错误提示

# 3.2. 文字转语音 - textToVoice

接口限制:暂未开放

青蛙小程序可以通过wxfaceapp.textToVoice进行文字转语音,并且播放

调用范例如下:

//获取青蛙相关信息
wxfaceapp.textToVoice({
  textToSpeak:"需要转语音播放的文字",
  success(res){
    console.log("success [textToVoice]")
    console.log(res.replyCode)
    console.log(res.reply)
    console.log(res.textSpoken)
  },
  fail(res){
    console.log("fail [textToVoice]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

输入参数如下:

参数 类型 说明
textToSpeak String 开发者想要进行文字转语音的文案

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示转文字并且播放成功
reply String 返回信息,成功回调返回"success"
textSpoken String 成功播放的文字内容

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"-1"表示转文字并且播放失败
reply String 错误具体信息

# 3.3. 数据写串口 - writeToSerialPort

接口限制:无

青蛙小程序可以通过wxfaceapp.writeToSerialPort将数据信息经由青蛙app,通过串口传入POS机,进行一些定制化功能开发,例如写入手机号,会员码等等

调用范例如下:

//获取青蛙相关信息
wxfaceapp.writeToSerialPort({
  msgToFlush:"需要传入串口至POS机的信息",
  success(res){
    console.log("success [writeToSerialPort]")
    console.log(res.replyCode)
    console.log(res.reply)
    console.log(res.flushedMsg)
  },
  fail(res){
    console.log("fail [writeToSerialPort]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

输入参数如下:

参数 类型 说明
msgToFlush String 开发者需要通过串口传入POS机的信息

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示转文字并且播放成功
reply String 返回信息,成功回调返回"success"
flushedMsg String 成功写入串口的信息

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"-1"表示写串口失败
reply String 错误具体信息

# 3.4. 启动小程序 - launchMp

接口限制:

  1. 该API只能在青蛙Pro上成功调用
  2. 暂时只支持运行在青蛙Pro前屏上的小程序启动背屏小程序
  3. 接口传入参数目前不支持miniappType=1,原因是目前小程序的开发版无法在青蛙上运行
  4. 由于背屏小程序的限制问题,目前needLogin参数必须设置为0,即不需要登录

请注意:此API可能会发生更新,未来将会支持青蛙Pro由背屏小程序启动前屏小程序,并且支持拓展miniappType,needLogin

青蛙Pro上的商户小程序可以通过wxfaceapp.launchMp,启动一个指定的背屏小程序,背屏小程序被启动后将会运行在青蛙Pro的背屏.启动校验成功后,前屏小程序将会收到启动成功的回调

调用范例如下:

//启动背屏小程序
wxfaceapp.launchMp({
  appId: "背屏小程序的Appid",
  hostAppId: "背屏小程序的主体ID",
  miniappType: 0,//小程序版本类型
  launchPage: "背屏小程序的启动页面",
  needLogin: 0,//是否需要登录态
  success(res) {
    console.log('launchMp suc')
    originThz.setData({
      launcMpResult: res.reply
    })
  },
  fail(res) {
    console.log('launchMp failed reply = ' + res.reply)
    originThz.setData({
      launcMpResult: res.reply
    })
  }
})

输入参数如下:

参数 类型 说明
appId String 需要启动的后屏小程序的AppId
hostAppId String 需要启动的后屏小程序的主体ID
miniappType int 小程序的版本信息{0:正式版;1:开发版;2:体验版}
launchPage String 小程序的启动页面
needLogin int 是否需要登录态{0:不需要;1:需要}

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"suc calling"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 后屏小程序正在启动,请勿重复启动
"-2" 青蛙小程序内部错误
"-3" 人脸支付已经在运行
"-4" 小程序参数设置有误
"-5" 当前机具不支持此功能
"-6" 机具不支持此功能

# 3.5. 退出小程序 - exitMp

接口限制:无

青蛙小程序可以通过exitMp主动的退出当前正在运行的小程序,同时清除用户当前的登录态信息(i.e.,再次进入某个需要用户登录的小程序,还需要进行刷脸登录操作)

调用范例如下:

//获取青蛙相关信息
wxfaceapp.exitMp({
  success(res){
  console.log("exit mini app!")
  }
})

具体错误码如下:

该API调用即生效,无回调信息

# 3.6. 小程序间消息发送 - postMsg

接口限制:

  1. 该API只能在青蛙Pro上成功调用
  2. 该API有传输内容限制,目前的限制为200个字符
  3. 这个接口能够发送作用的前提是,青蛙Pro的前屏和背屏的小程序已经处于运行状态

请注意:此API可能会发生更新,可能会拓宽字符限制,运行传输更多不同的内容,例如图片

青蛙Pro上运行的小程序可以通过wxfaceapp.postMsg,向前屏/背屏小程序发送本地文本消息,进而让前后屏小程序之间可以通过本地通信.

调用范例如下:

//向另一端屏幕上的小程序发送消息
wxfaceapp.postMsg({
  targetAppid: "接受消息的小程序APPID",
  content: "this is frog jsapi demo, saying hello",
  success(res) {
    console.log('sendMsgResult suc')
  },
  fail(res) {
    console.log('sendMsgResult failed reply = ' + res.reply)
  }
})

输入参数如下:

参数 类型 说明
targetAppid String 需要接受消息的小程序的AppId
content String 传递的消息内容

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"suc sending msg"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 后屏小程序正在启动,请勿重复启动
"-2" 接收端的小程序Appid不匹配
"-3" 字符数超出限制
"-4" 输入参数有误
"-5" 小程序运行状态有误,不支持消息接收和发送
"-6" 机具不支持此功能
"-7" 未知错误
"-8" 发送消息超时

# 3.7. 小程序间消息接受 - onRemoteMessage

接口限制:

  1. 该API只能在青蛙Pro上成功调用

请注意:此API可能会发生更新,可能会拓宽字符限制,运行传输更多不同的内容,例如图片

青蛙Pro上的商户小程序可以通过wxfaceapp.onRemoteMessage,接受另一屏幕的小程序所传来的消息.

调用范例如下:

//接受另一端屏幕上的小程序发来的消息
wxfaceapp.onRemoteMessage(function (res) {
  console.log("onRemoteMessage retCode = " + res.replyCode)
  originThz.setData({
    sendMsgFrom: res.senderAppid,
    msgContent: res.content
  })
})

回调参数如下:

参数 类型 说明
senderAppid String 发送本条消息的小程序Appid
content String 传递的消息内容

# 4.支付能力API

# 4.1. 启动刷脸支付 - facePay

接口限制:无

请注意:该接口的JsEvent消息,后续可能会收归为统一的一个接口

青蛙小程序可以通过wxfaceapp.facePay启动青蛙app的刷脸支付能力,该接口调用后,会呼启青蛙app,执行基本的刷脸支付流程

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  success(res){
    console.log("success [launchFaceApp]")
    console.log(res.replyCode)
    console.log(res.reply)
  },
  fail(res){
    console.log("fail [launchFaceApp]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示转文字并且播放成功
reply String 返回信息,成功回调返回"success"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 未知错误
"-2" 青蛙小程序内部错误
"-3" 人脸支付已经在运行
"-4" 无网络
"-5" 当前机具不支持此功能
"-6" 超时

使用wxfaceapp.facePay的API,开发者可用利用小程序启动青蛙app的刷脸支付,考虑到开发者可能会希望监听整个刷脸支付的流程,青蛙小程序会以JsEvent的形式,将刷脸支付的结果告知注册回调的小程序。

启动刷脸后,商户小程序开发者可用通过注册4个jsEvent,来达到监听刷脸流程的效果,根据人脸识别,以及支付结果查询两大场景,可以把他们分为:

  • 刷脸成功:onFacePayPassEvent
  • 刷脸失败:onFacePayFailedEvent
  • 查单成功:onQueryPaymentSucEvent
  • 查单失败:onQueryPaymentFailedEvent
# 刷脸成功 - onFacePayPassEvent

接口限制:无

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  success(res){
    console.log("success [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
    //刷脸成功Event 建议配合facePay的调用结果进行注册
    wxfaceapp.onFacePayPassEvent(function (res) {
      console.log("onFacePayPassEvent retCode = "+res.replyCode)
    })
  },
  fail(res){
    console.log("fail [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示成功
reply String 返回信息,成功回调返回"face pay finished"
# 刷脸失败 - onFacePayFailedEvent

接口限制:无

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  success(res){
    console.log("success [launchFaceApp]")
    console.log(res.replyCode)
    console.log(res.reply)
    //刷脸失败Event 建议配合facePay的调用结果进行注册
    wxfaceapp.onFacePayFailedEvent(function (res) {
      console.log("onFacePayFailedEvent retCode = "+res.replyCode)
    })
  },
  fail(res){
    console.log("fail [launchFaceApp]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误信息

具体错误码如下:

错误码 说明
"-1" 未知错误
"-6" 超时
"-7" 用户取消支付
"-8" 用户刷脸多次失败,转二维码支付

# 查单成功 - onQueryPaymentSucEvent

接口限制:无

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  success(res){
    console.log("success [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
    //查单成功Event
    wxfaceapp.onQueryPaymentSucEvent(function (res) {
      console.log("onQueryPaymentSucEvent retCode = " + res.replyCode)
    })
  },
  fail(res){
    console.log("fail [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示成功
reply String 返回信息,成功回调返回"query payment success"
# 查单失败 - onQueryPaymentFailedEvent

接口限制:无

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  success(res){
    console.log("success [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
    //查单失败Event
    wxfaceapp.onQueryPaymentFailedEvent(function (res) {
      console.log("onQueryPaymentFailedEvent retCode = " + res.replyCode)
    })
  },
  fail(res){
    console.log("fail [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误信息

具体错误码如下:

错误码 说明
"-1" 未知错误
"-6" 超时
"-10" 查单失败
"-11" 用户刷脸多次失败,转二维码支付
"-12" 查单参数有误

# 4.2 监听扫码支付 - listenCodePayment

接口限制:无

请注意:该接口未来可能会发生变更,考虑到业务场景和安全,未来可能会下线该API

主要服务于青蛙Pro,微信青蛙机具同样具备扫码支付的能力,当用户使用手机扣款码进行扫码支付时,小程序能够通过listenCodePayment对用户的扫码支付事件进行监听。

调用范例如下:

//监听扫码器
wxfaceapp.listenCodePayment({
  success(res){
    //注册事件
    wxfaceapp.onCodePayEvent(function (res) {
       console.log("onCodePayEvent retCode = " + res.replyCode)
    })
  }
})

具体错误码如下:

API本身只是一条注册通知,并不存在错误码

注册扫码支付监听后,商户开发者可以注册扫码器的扫码Event

# 扫码支付事件监听 - onCodePayEvent

接口限制:无

请注意:该接口未来可能会发生变更,考虑到业务场景和安全,未来可能会下线该API

当使用listenCodePayment进行扫码事件监听的注册后,可以使用onCodePayEvent注册JsEvent,来接受扫码支付的事件通知,当接收到通知后,小程序可以选择自己进行对应支付的结果查询。

调用范例如下:

//注册扫码支付事件
wxfaceapp.onCodePayEvent(function (res) {
  console.log("onCodePayEvent retCode = " + res.replyCode)
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示成功
reply String 返回信息,成功回调返回"code payment happens"

# 4.3. 快速支付 - quickPay

接口限制:

  1. 使用此接口的小程序必须使用刷脸登录,进行登录启动,如果是无登录要求启动的小程序,此API不会被正常执行
  2. 此API在一次启动过程中(i.e.,刷脸登录小程序->退出小程序,被称为1次启动过程),只能被调用一次
  3. 从刷脸登录小程序开始算起,此API具有4分钟的有效时间,超出有效时间,也无法进行快速支付

请注意:该接口未来可能会发生变更,可能会增加时间,或者直接支持微信小程序原生的支付接口

对于很多需要刷脸登录才能启动的小程序来说,如果想要在小程序内再次通过收银机传码支付,那么就必须调用wxfaceapp.facePay再次进行刷脸支付,这样对于一个用户来说,要进行两次刷脸,用户体验不好。

所以对于有这种需求的商户来说,使用快速支付wxfaceapp.quickPay,是一个更好的选择。

在进行刷脸登录后,在规定的时间内,商户小程序开发者可用通过调用wxfaceapp.quickPay直接向收银机进行传码支付。

调用范例如下:

//快速支付
wxfaceapp.quickPay({
  success(res) {
    console.log('quickpay suc')
  },
  fail(res) {
    console.log('quickpay failed reply = '+res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"suc launching quick pay"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 后屏小程序正在启动,请勿重复启动
"-2" 接收端的小程序Appid不匹配
"-3" 字符数超出限制

# 4.4. 快速支付是否可用 - ableToQuickPay

接口限制:无

在Section4.3我们说过,对于不想进两次刷脸,完成登录+支付操作的商户们来说,使用quickPay是一个很好的做法,但是考虑到商户小程序可能在多个场景中被运行,且quickPay本身有时间限制,所以提供了wxfacepay.ableToQuickPay这样一个API,用于在商户想要进行支付时,进行是否能够快速支付的判断.

通过这样的方式,商户能够进行选择:

  • 在可以进行快速支付的时候:使用快速支付wxfaceapp.quickPay
  • 在不可用进行快速支付的时候:使用兜底逻辑,进行二次刷脸,完成支付wxfaceapp.facePay

调用范例如下:

//是否能够快速支付
wxfaceapp.ableToQuickPay({
  success(res) {
    console.log('check facecode suc')
  },
  fail(res) {
    console.log('check facecode failed')
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"ok"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 后屏小程序正在启动,请勿重复启动
"-2" 接收端的小程序Appid不匹配
"-3" 字符数超出限制

# 4.5. 获取上一笔支付记录 - getLastPayResult

接口限制:

  1. 此接口和小程序的场景值有关,是为支付结果页小程序所使用的
  2. 此API中所贮藏的结果只允许被获取一次,再次尝试获取将无法获取到对应的支付记录
  3. 从上一次的支付完成后开始记录,结果可查询时间为90秒,超出有效时间后,也无法获取到对应的支付记录

请注意:该接口未来可能会发生变更,可能会增加更多的信息,修改调用方式

在结果页小程序这一场景中,考虑到很多这个场景下启动的小程序将会需要一些例如开发票、支付后营销等与支付金额相关的业务,所以在这一场景下的小程序,可以使用wxfaceapp.getLastPayResult来获取刚刚(上一笔)成功支付的交易记录。

调用范例如下:

//获取上一笔交易记录
wxfaceapp.getLastPayResult({
  success(res) {
    console.log('getLastPayResult suc')
    originThz.setData({
      payResultPeply: res.reply,
      payResult: "金额:" + res.totalFee + "折扣:" + res.discountFee
    })
  },
  fail(res) {
    console.log('getLastPayResult failed reply = ' + res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"fetch suc"
totalFee String 消费金额,单位:分
discountFee String 折扣金额,单位:分

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码见下表
reply String 错误具体信息

具体错误码如下:

错误码 说明
"-1" 后屏小程序正在启动,请勿重复启动
"-2" 查询不到上一笔支付结果

# 5. 特殊能力API

# 5.1. 会员场景特殊指令 - onSpecialCtrlEvent

接口限制:

  1. 建议会员小程序监听这个JsEvent,承载其他业务的小程序没有必要监听这个Event
  2. 由于场景较小,建议在page.onShow生命周期函数回调后再进行注册

请注意:该接口未来可能会发生变更,采取更加通用的方式解决问题

在会员场景下,小程序支持收到收银员的控制(青蛙的键盘/青蛙Pro的背屏按钮),传递特定消息的功能,通过注册wxfaceapp.onSpecialCtrlEvent可以做到这点,具体如何触发事件,可以参考会员小程序场景的相关文档,或者联系技术支持.

调用范例如下:

//监听会员场景的特殊指令
wxfaceapp.onSpecialCtrlEvent(function (res) {
  console.log("onSpecialCtrlEvent ctrlCode = " + res.ctrlCode)
  originThz.setData({
    receivedCtrl: res.ctrlCode,
    receivedCtrlContent: res.ctrlMsg
  })
})

成功回调参数如下:

Object res

参数 类型 说明
ctrlCode String 返回码,{0:传码;1:收款}
ctrlMsg String 返回信息,传码场景下,返回"传码",收款场景下,返回"收款"