青蛙小程序 - 特殊API接口

1.背景

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

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

微信小程序已经具备了很多小程序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

2.13版本修改:

新增4个字段:

  • appVersion
  • deviceInfo
  • runningMode
  • screenInfo

**接口限制:**无

项目 不支持的具体条目
模式相关
机具相关
屏幕相关

青蛙小程序可以通过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 该青蛙机具中青蛙App的版本号
osStatus String 青蛙机具与人脸App状态,成功回调返回"valid"
osSerialNumber String 该青蛙机具的设备号
appVersion String 预留字段,后期用于标识小程序容器版本号,目前与osVersion相同
deviceInfo String 设备信息{FacePay-L1:青蛙基础版;FacePay-L2:青蛙PRO版;unofficial-device:非官方设备}
runningMode String 运行模式{sdk:sdk运行模式;lpos:青蛙运行模式}
screenInfo String 小程序运行的屏幕(非PRO设备不需要关心){front-screen:前屏;back-screen:背屏;}

失败回调参数如下:

Object res

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

3.2. 数据写串口 - writeToSerialPort

接口限制:

  1. 该接口仅支持青蛙模式,不支持SDK模式
  2. 该接口仅支持
项目 不支持的具体条目
模式相关 SDK模式
机具相关 非微信支付官方设备(i.e.,非青蛙PRO,青蛙基础版)
屏幕相关

青蛙小程序可以通过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.3. 启动小程序 - launchMp

2.13版本修改:

  1. 后屏目前已经开放扫码登录,如果已经扫码登录完成,则needLogin参数无需限制为0

接口限制:

  1. 该接口仅支持青蛙模式,不支持SDK模式
  2. 该API只能在青蛙PRO上成功调用
  3. 目前只支持青蛙PRO,前屏小程序,启动后屏小程序
  4. 接口传入参数目前不支持miniappType=1,原因是目前小程序的开发版还无法在青蛙机具上正确运行
项目 不支持的具体条目
模式相关 SDK模式
机具相关 青蛙基础版,非微信支付官方设备
屏幕相关 后屏

青蛙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.4. 退出小程序 - exitMp

接口限制:无

项目 不支持的具体条目
模式相关
机具相关
屏幕相关

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

调用范例如下:

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

具体错误码如下:

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

3.5. 小程序间消息发送 - postMsg

接口限制:

  1. 该API只支持青蛙模式,不支持SDK模式
  2. 该API只能在青蛙PRO上成功调用
  3. 该API有传输内容限制,2.13版本及其以上版本,限制字符数为2000字符
  4. 这个接口能够发送作用的前提是,青蛙PRO的前屏和后屏的小程序已经处于运行状态
项目 不支持的具体条目
模式相关 SDK模式
机具相关 青蛙基础版,非微信支付官方设备
屏幕相关

青蛙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.6. 小程序间消息接受 - onRemoteMessage

接口限制:

  1. 该API只支持青蛙模式,不支持SDK模式
  2. 该API只能在青蛙PRO上成功被激活
项目 不支持的具体条目
模式相关 SDK模式
机具相关 青蛙基础版,非微信支付官方设备
屏幕相关

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

调用范例如下:

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

回调参数如下:

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

3.7. 注册监听键盘输入 - registKeyBoard

2.13版本修改:

  1. 目前该指令将会支持青蛙一代和青蛙PRO两种机具

接口限制:

  1. 该API只支持青蛙模式,不支持SDK模式
项目 不支持的具体条目
模式相关 SDK模式
机具相关
屏幕相关

请注意:

1.由于不同的商户可能会使用不同的键盘,需要监听的KeyCode没有一个统一的标准,所以KeyCode部分我们决定开放给开发者自行定制。在使用前,商户开发者需要自行确认自己使用的键盘所用的KeyCode都是哪些

青蛙小程序可以通过wxfaceapp.registKeyBoard进行键盘输入的监听,具体监听哪个按键,由商户自己定义

该API主要用于进行某些特殊的商户自定义指令响应(e.g.,按下键盘按钮“1”,小程序跳转至某个特定页面)。

如果商户需要利用小键盘进行一些输入操作(e.g.,输入支付金额),那么不需要使用本接口,即可完成,推荐的做法有:

  1. 使用小程序的Input组件,连接上外接小键盘,完成输入
  2. 使用商户自定制的小程序数字软键盘,直接完成输入

调用范例如下:

//需要监听的键盘按键,所对应的KeyCode
data: {
curInputValue: "",
keyCodeLst: [
  { keyCode: "144" }, //青蛙原生小键盘按键 - 1
  { keyCode: "145" }, //青蛙原生小键盘按键 - 2
  { keyCode: "146" }, //青蛙原生小键盘按键 - 3
  { keyCode: "147" }, //青蛙原生小键盘按键 - 4
  { keyCode: "148" }, //青蛙原生小键盘按键 - 5
  { keyCode: "149" }, //青蛙原生小键盘按键 - 6
  { keyCode: "157" }],//青蛙原生小键盘按键 - +号
info: ""
},

//注册键盘监听
wxfaceapp.registKeyBoard({
  keyCodeList: this.data.keyCodeLst,
  success(res) {
    console.log("success [registKeyBoard]")
    console.log(res.replyCode)
    console.log(res.reply)
  },
  fail(res) {
    console.log("fail [registKeyBoard]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})


输入参数如下:

参数 类型 说明
keyCodeList 数组 定义了需要监听的各个按键所对应的AndroidKeyCode注意,此输入不可为空,数组中的某个子Item也不可为空

回调参数如下:

参数 类型 说明
replyCode String 返回码,返回0表示成功,返回-1表示输入参数解析失败
reply String 返回信息,注册成功返回“Success register to listen keyboard event”

3.8. 监听键盘输入 - onKeyBoardEvent

在利用Section3.8的,wxfaceapp.registKeyBoard进行了键盘监听的注册后,我们可以通过onKeyBoardEvent来监听我们想要的键盘按键事件,做出相应的处理。

调用范例如下:

//注册键盘监听
wxfaceapp.registKeyBoard({
  keyCodeList: that.data.keyCodeLst,
  success(res) {
    console.log("success [registKeyBoard]")
    //注册成功后,设置键盘按键响应回调
    wxfaceapp.onKeyBoardEvent(function (res) {
      console.log("onKeyBoardEvent name = " + res.keyName)
    })
  }
})

回调参数如下:

参数 类型 说明
keyName String 返回码,返回0表示成功

4.支付能力API

4.1. 启动刷脸支付 - facePay

2.12版本修改:

  1. 该接口支持通过传入参数requireFaceCode,控制最终生成的付款码流向

接口限制:

  1. 此接口无法用于SDK模式下结果页小程序

请注意:

  1. 该接口重复调用,重新登录后,opendata和商户的相关页面不会立刻刷新
项目 不支持的具体条目
模式相关 不支持SDK模式下的结果页小程序调用,其他均支持
机具相关
屏幕相关

请注意:

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

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

调用范例如下:

//获取青蛙相关信息
wxfaceapp.facePay({
  requireFaceCode : //是否需要获取付款码返回给小程序
  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)
  }
})

输入参数如下:

参数 类型 说明
requireFaceCode Boolean {true,false}是否需要获取支付付款码,填入true,付款码将不会传入收银机,而会通过onFacePayPassEvent直接回传给小程序,用于小程序独立收银。如不填写则为false。

成功回调参数如下:

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)
      //faceCode,在传入requireFaceCode=true时起效
    	console.log("onFacePayPassEvent faceCode = "+res.faceCode) 
    })
  },
  fail(res){
    console.log("fail [launchFacePay]")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示成功
reply String 返回信息,成功回调返回"face pay finished"
faceCode String 返回付款码,当开发者调用wxfaceapp.facePay传入requireFaceCode=true时才会返回

刷脸失败 - 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

接口限制:

  1. 此接口仅支持青蛙模式,不支持SDK模式
  2. 此接口仅支持青蛙PRO机具
项目 不支持的具体条目
模式相关 SDK模式
机具相关 青蛙基础版,非微信支付官方设备
屏幕相关

2.12版本修改:

1.此接口在青蛙PRO上支持多种类型的付款码,条形码,二维码,而不仅仅只是扣款码

2.13版本修改:

1.此接口现在在**青蛙基础版(青蛙一代)**上不再支持,请商户开发者们做好适配

请注意:

本接口的作用是进行声明,即向青蛙App声明,希望使用其扫码器相关能力,其后续的扫码结果,并不在此接口中返回。

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

目前此接口仅支持青蛙PRO,其扫码器相关能力也将完全通过此接口开放,支持监听各色付款码,条形码,以及二维码。

本接口的作用是进行声明,即向青蛙App声明,希望使用其扫码器相关能力,其后续的扫码结果,并不在此接口中返回。如果需要接收扫码器的具体扫码结果,请配合onCodePayEvent接口使用。

调用范例如下:

//声明监听扫码器
wxfaceapp.listenCodePayment({
  success(res){
    //被扫码回调事件
    wxfaceapp.onCodePayEvent(function (res) {
       console.log("onCodePayEvent retCode = " + res.replyCode)
       //被扫码到的具体的码
       console.log("onCodePayEvent code scanned = " + res.code)
    })
  }
})

具体错误码如下:

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

扫码支付事件监听 - onCodePayEvent

接口限制:

  1. 此接口仅支持青蛙模式,不支持SDK模式
  2. 此接口仅支持青蛙PRO机具
项目 不支持的具体条目
模式相关 SDK模式
机具相关 青蛙基础版,非微信支付官方设备
屏幕相关

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

调用范例如下:

//注册扫码支付事件
wxfaceapp.onCodePayEvent(function (res) {
  console.log("onCodePayEvent retCode = " + res.replyCode)
  //被扫码到的具体的码
  console.log("onCodePayEvent code scanned = " + res.code)
})

回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示成功
reply String 返回信息,成功回调返回"code payment happens"
code String 当扫码器感知到码后,被扫描的码的具体值

4.3. 快速支付 - quickPay

2.13版本修改:

  1. 增加

接口限制:

  1. 此接口在背屏上无法使用(背屏因无法获得扣款码,不支持快速支付)
  2. 使用此接口的小程序必须使用刷脸登录,进行登录启动,如果是无登录要求启动的小程序,此API不会被正常执行
  3. 此API在一次启动过程中(i.e.,刷脸登录小程序->退出小程序,被称为1次启动过程),只能被调用一次
  4. 从刷脸登录小程序开始算起,此API具有45秒的有效时间,超出有效时间,也无法进行快速支付
项目 不支持的具体条目
模式相关
机具相关
屏幕相关 背屏

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

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

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

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

调用范例如下:

//快速支付
wxfaceapp.quickPay({
  requireFaceCode: true, // 需要付款码
  success(res) {
    console.log('quickpay suc')
    // 返回的扣款码,requireFaceCode=true时返回
    console.log('ret faceCode = '+res.faceCode)
  },
  fail(res) {
    console.log('quickpay failed reply = '+res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示启动后屏小程序成功
reply String 返回信息,成功回调返回"suc launching quick pay"
faceCode String 返回付款码,当开发者调用wxfaceapp.quickPay传入requireFaceCode=true时才会返回

失败回调参数如下:

Object res

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

具体错误码如下:

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

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

接口限制:

  1. 此接口在背屏上无法使用(背屏因无法获得扣款码,不支持快速支付)
项目 不支持的具体条目
模式相关
机具相关
屏幕相关 背屏

在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

2.13版本修改:

  1. 此接口下线,不再提供服务
  2. 如果是结果页小程序,希望获取支付后相关信息,请参考启动参数一章,了解相关必要信息

5. 登录能力API

5.1. 登录能力概览

总体来说,青蛙小程序的登录分为2大类:

  • 小程序内登录:此类小程序对应那些商户设置为需要用户登录的小程序,他们在启动后,可以完全按照官方提供的登录指引进行登录
  • 运行中登录:此类小程序对应那些设置为不需要用户登录,且非背屏小程序的小程序,他们在启动后,无法调用用户相关的API(i.e.,wx.login,wx.getUserInfo),他们需要完成额外的登录过程,然后进行正常的官方登录后,才可以调用相关API

为什么会有这些区别?原因在于,在手机上运行的小程序,他们的登录态是由微信客户端提供的。

而在青蛙机具上运行的小程序,他们的登录态是由青蛙刷脸App提供的,而这个青蛙刷脸App作为一个共享设备上的App,它的登录态获取过程,又和微信客户端有不少区别。

开发者在微信手机端的微信小程序上做的登录步骤可能是这样的:

sequenceDiagram participant 微信客户端 participant 商户小程序 participant 商户后台 微信客户端->>商户小程序: 启动小程序 微信客户端->>商户小程序: App::onLaunch() 商户小程序->>商户小程序: wx.login获取code 商户小程序->>商户后台: 利用code请求登录 商户后台-->>商户小程序: 完成登录

而青蛙App不同,青蛙App并不会像微信客户端那样,可以将用户的登录态贮藏并且续期。青蛙App的登录态都是短暂的,不续期的,所以在青蛙App上,进行小程序的启动/登录会有所区别。

但是对于小程序内登录来说,由于开发者设置了该小程序需要用户登录。在启动这个小程序前,青蛙App会进行刷脸登录,以获取当前刷脸用户的微信登录态,之后才会启动小程序,所以这种登录类型,商户开发者在实现登录逻辑时,可以采取和手机小程序一模一样的做法。流程如下:

sequenceDiagram participant 青蛙刷脸App participant 商户小程序 participant 商户后台 alt 前屏小程序 青蛙刷脸App->>青蛙刷脸App: 刷脸登录获取用户微信登录态 else 背屏小程序 青蛙刷脸App->>青蛙刷脸App: 背屏扫码获取用户微信登录态 end 青蛙刷脸App->>商户小程序: 启动小程序 青蛙刷脸App->>商户小程序: App::onLaunch() 商户小程序->>商户小程序: wx.login获取code 商户小程序->>商户后台: 利用code请求登录 商户后台-->>商户小程序: 完成登录

可以看到,唯一不同的区别就是在启动小程序前,青蛙App需要执行一次刷脸,获取用户登录态的流程,这有别于手机微信端的直接启动。但是作为小程序开发者。并不会感知这一流程。

区别更大的是运行中登录,这种登录模式,建立在开发者将他们的小程序设置为设置为不需要用户登录,比如首页常驻小程序。这类小程序,启动时,青蛙刷脸App并不会提供登录态支持,所以他们将以无登录态的方式启动,这个时候,所有和用户身份相关的API都会失效(i.e.,wx.login,wx.getUserInfo,wx.checkSession),在这种情况下,小程序如果想登录,获取用户相关的信息,需要遵照下面的流程:

sequenceDiagram participant 青蛙刷脸App participant 商户小程序 participant 商户后台 青蛙刷脸App->>商户小程序: 启动小程序 青蛙刷脸App->>商户小程序: App::onLaunch() 商户小程序->>商户小程序: 运行一段时间 商户小程序->>青蛙刷脸App: wxfaceapp.isLoginOnFaceApp 青蛙刷脸App-->>商户小程序: 返回结果 alt 返回结果为True 商户小程序->>商户小程序: wx.login获取code 商户小程序->>商户后台: 利用code请求登录 商户后台-->>商户小程序: 完成登录 else 返回结果为False 商户小程序->>青蛙刷脸App: wxfaceapp.faceLogin 青蛙刷脸App->>青蛙刷脸App: 刷脸登录获取用户微信登录态 青蛙刷脸App-->>商户小程序: 告知结果 商户小程序->>商户小程序: wx.login获取code 商户小程序->>商户后台: 利用code请求登录 商户后台-->>商户小程序: 完成登录 end

可以看到,目前针对这一情况,我们提供了两个JsApi,接下来我们会详细解释这两个API的使用方法

5.2. 查看青蛙App此时是否具有登录态 - isLoginOnFaceApp

2.12版本修改:

  1. 增加此接口
项目 不支持的具体条目
模式相关
机具相关
屏幕相关

该接口用于小程序判断此时青蛙App是否具备用户登录态,我们推荐,开发者在进行运行中登录时使用这个能力,如果判断青蛙App此时不具备用户登录态,需要使用5.3中的JsApi先让青蛙App具备用户登录态,然后再进行小程序内登录。反之,直接进行小程序内登录即可。

调用范例如下:

wxfaceapp.isLoginOnFaceApp({
  success() {
    //成功,说明此时青蛙App具备登录态,可以进行小程序内登录
    console.log("[isAlreadyLogin] is login on face app, free to call [wx.login]")
  },
  fail() {
    //失败,说明此时青蛙App不具备登录态,需要进行刷脸登录获取登录态,然后才可以进行小程序内登录
    console.log("[isAlreadyLogin] not login on face app, free to call [faceLogin]")
  }
})

由于这个接口没有回调参数,和入参,所以参数讲解部分省略。

5.3. 青蛙刷脸登录 - faceLogin

2.13版本修改:

  1. 提供enableMultiLogin选项,开启后该接口可以在登录后,重复调用,进行登录态的反复切换
  2. 提供relaunchUrl参数,传入正确的页面路径后,可以在刷脸登录完成后进行自动路由

2.12版本修改:

  1. 增加此接口

接口限制:

  1. 此接口无法在青蛙PRO背屏被调用(背屏登录使用扫码登录即可)
项目 不支持的具体条目
模式相关
机具相关
屏幕相关 背屏

该接口用于在运行中登录,这种类型下,由小程序主动触发,让青蛙刷脸App具备用户登录态。只有在青蛙刷脸App具备了用户登录态之后,小程序才能通过小程序内登录来进行登录,获取和用户相关的信息。

输入参数如下:

参数 类型 说明
enableMultiLogin Boolean 是否开启多次登录,默认为false{若传入true:则可以多次调用该接口,进行登录态的切换;若传入false:在单次调用,且登录成功后,该接口将不可用,使用logoutOnFaceApp退出登录后,该接口再次可用}
relaunchUrl String 默认为空,若传入正确的页面URL,则App会在登录成功后,重新路由至传入页面

调用范例如下:

wxfaceapp.faceLogin({
  //开启重复登录
  enableMultiLogin:true,
  //登录成功后,自动路由至此页面
  relaunchUrl:"pages/pay/pay",
  success(res) {
    console.log("[faceLogin] success")
    console.log(res.replyCode)
    console.log(res.reply)
  },
  fail(res) {
    console.log("[faceLogin] failed")
    console.log(res.replyCode)
    console.log(res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示登录成功
reply String 返回信息,成功回调返回"face login suc",如果已经具备登录态,会直接返回”already in login status, no need to face login“

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 具体返回码和facePay是一样的
reply String 错误具体信息

5.4. 退出登录 - logoutOnFaceApp

2.13版本修改:

  1. 增加此接口

接口限制:

  1. 该接口无法在背屏使用
项目 不支持的具体条目
模式相关
机具相关
屏幕相关 背屏

请注意:

  1. 此接口调用后,小程序操作用户身份相关的API都将失效
  2. 如果想重新登录,请重新走faceLogin的流程

该接口用于在运行中登出,这种类型下,由小程序主动触发,让青蛙刷脸App,和当前运行中的小程序同时失去用户登录态。请注意,API调用成功后,小程序操作用户身份相关的API都将失效。

调用范例如下:

//退出登录
wxfaceapp.logoutOnFaceApp({
  success(res) {
    //退出登录成功后,小程序和青蛙App用户登录态都将完成注销
    console.log("[faceLogout] suc, msg = " + res.reply)
  },
  fail(res) {
    console.log("[faceLogout] failed, msg = " + res.reply)
  }
})

成功回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,返回"0"表示登录成功
reply String 返回信息,成功回调返回"logout suc!"

失败回调参数如下:

Object res

参数 类型 说明
replyCode String 返回码,“-1”代表登出失败
reply String 返回信息,失败回调返回"logout suc!"

6. 特殊能力API

6.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 返回信息,传码场景下,返回"传码",收款场景下,返回"收款"
上次更新: 1/16/2020, 2:15:53 PM