关闭
公众号二维码

# 以「SDK模式」接入刷脸支付的设备


# 第一部分 概念说明、适用条件

本文档旨在介绍:以「SDK 模式」接入的多种刷脸支付设备上,如何开发、运行小程序。

# 产品价值

小程序可以运行在不同终端上。在手机微信客户端或刷脸支付设备上运行的小程序,本质相同,有着相同的技术原理、帐号体系。在不同运行环境,却有部分能力差异,但更重要的是应用场景的差异。例如:

  • 从个人手机场景,到门店智能硬件的场景
  • 从仅由用户操作,到成为商家的经营工具,由店员与顾客实时互动
  • 用户在线下设备亦可临时登录微信身份,从而连接起物理世界与数字世界

刷脸支付设备运行小程序,容易获得以下特性:

  • 连接微信

    微信身份( 用户帐号体系 / 用户信息授权 / 连接关系链)

    微信服务(订阅服务通知 / 企微加群插件 / 电子发票… )

  • 多端融合

    跨终端 - 跨场景 - 线上线下:服务融合 流量互通

  • 低成本开发运维运营

    开发简单 / 敏捷更新 / 存量应用迁移 / 用户认知成熟 / 易于传播

以上可能带来创新机会。如何连接微信,构建多端融合的服务场景,值得思考探索。

# 关键概念

微信小程序硬件框架( Wechat Mini-Program Framework,简称小程序框架或 [WMPF] )

  • 是微信客户端之外的小程序运行环境,由微信官方提供。为方便理解,可以将「小程序框架」与「小程序应用」,类比为「浏览器」与「浏览器插件」的关系。
  • [WMPF] 可广泛通用于多种智能硬件,本身不限于刷脸支付设备使用。
  • 在刷脸支付设备上使用 [WMPF],相较于其他设备会有所不同(包括接入流程、部分接口设计),本文档将作出说明。

# 文档用法

  1. 本文档将介绍 [WMPF] 在刷脸支付设备上的使用方法,包括专用的接入流程及接口设计。若这部分内容与 [WMPF] 的通用文档描述有差异,请以本文档为准。
  2. 除本文档外,还有必要阅读以下文档,以完整了解本文档所未涉及的通用能力、进行通用功能开发:
  1. 如有疑问或困难,请前往:

# 适用条件

设备类型

  • 暂只支持 Android 设备。
  • 以「SDK 模式」接入刷脸支付的设备。

注:在「青蛙模式」中,青蛙 app 已集成小程序框架,只需开发小程序并在商户平台将其下发至设备运行,见青蛙运行小程序产品文档

  • 【重要】 设备已完成软硬件接入流程、已绑定「铺设服务商」帐号(MchID)。

操作参考:设备关系绑定

必备应用

  • 刷脸 SDK,v2.20.1 或以上
  • [WMPF],v1.0.3 或以上
  • IoT Service,v1.3.100 或以上

建议由设备商将以上应用预置在 ROM 中。

硬件配置要求

  • CPU:四核 2 GHz 或以上
  • 储存:2GB RAM + 8GB ROM 或以上

# 第二部分 接入流程、权限注册

本部分,将指引你使用刷脸支付设备接入 [WMPF] 并绑定所需运行的小程序。

流程中涉及的三个平台 作用 地址
微信支付商户平台 以铺设服务商帐号身份,管理刷脸支付设备 [查看]
微信终端合作平台 使特定设备获得 [WMPF] 的使用权限,绑定 设备-主应用-小程序应用 的关系 [查看]
微信开放平台 注册「主应用」并作主体认证,使之获得调起小程序的权限 [查看]

# 流程总览

刷脸支付设备接入WMPF的流程

# 详细说明

0.铺设服务商帐号(MchID) 登录商户平台,进入「刷脸SDK接入小程序框架」功能

1. 激活「微信终端合作平台」帐号,自动完成设备类型注册,获取 product_idmodel_name

2. 使用设备的主应用(即商户app)在微信开放平台创建移动应用,获取该移动应用的 AppID 即hostAppId,及AppSecretaccess_token

  1. 开放平台帐号,需完成企业主体认证
  2. 创建移动应用一般需 7 天审核,请尽早申请。同一应用 apk 只可以创建一个移动应用 AppID。
  3. Android 应用签名生成工具

3. 绑定设备上的主应用(即商户app)所需运行的小程序 AppID。

  1. 此步骤仅为获取小程序的运行权限,调起行为由主应用通过终端接口发起。
  2. 主体限制:同一移动应用,可绑定无限个相同主体小程序、50 个非同主体小程序。

4. 设备注册为后台接口,详见调用方法

  1. 可在终端合作平台的「查询设备状态」功能,检查设备是否成功注册。
  2. 使用mmpayiotdevicemanagelogicsvrAPI,可从微信支付商户平台批量导出设备列表,其中
    • device_id 即「设备序列号(SN)」 。
    • model_name 即「设备型号」。

至此,接入流程完成。

特定设备(SN)、特定主应用(AppID, 或称 hostAppId ),将可调起 [WMPF] 运行特定小程序(AppID)。


# 第三部分 接口功能、终端开发

本部分,将介绍 [WMPF] 在刷脸支付设备上的功能及调用方法,指引你完成主应用和小程序的开发:

  1. 主应用
    • 承担设备基础功能的原生应用,一般为收银软件,或称为「商户 app」。
    • 作为 [WMPF] 的调起方,需集成 [WMPF] 的 aar 并作接口开发。
    • 作为 刷脸支付 的调起方,需继承 刷脸支付SDK 并做接口开发。
    • 商户应用示例源码可以参考wmpf_demo,构建模式需切换到wxfacepay。
  2. 小程序
    • 由主应用通过 [WMPF] 调起运行,生命周期由主应用控制(可在交互流程中临时调起、使用后关闭;也可保持常驻运行)。
    • 线上线下场景,可运行相同的小程序(AppID)。可沿用手机微信客户端上的大部分能力,也可使用基于硬件场景额外提供的能力。
    • 小程序示例源码可以参考wxfacepay-wmpf-mp-demo

# 使用示例

# 1. 小程序的两种登录、启动模式

  • 先登录再启动小程序
  • 先启动小程序再登录
  sequenceDiagram     participant M as 主应用     participant F as 刷脸 SDK     participant W as WMPF     participant A as 小程序应用        M->>F: 初始化、获取调用权限     note over M,F: initWxpayface
getWxpayfaceRawdata
get_wxpayface_authinfo     M->>W: 激活     note over M,W: IPCInvokerTask_ActivateDeviceByIoT     M->>W: 预置刷脸调用参数     note over M,W: IPCInvokerTask_InitWxFacePayInfo
传入 getWxpayfaceCode 的调用参数 opt 先登录再启动小程序     M->>W: 请求用户刷脸登录     note over M,W: IPCInvokerTask_AuthorizeByWxFacePay     W->>F: (自动)     F->>F: 用户刷脸登录     W-->>M: 登录凭据+用户信息     M->>W: 启动小程序     note over M,W: IPCInvokerTask_LaunchWxaApp     W->>A: 启动小程序(带登录态) end opt 先启动小程序再登录     M->>W: 启动小程序     note over M,W: IPCInvokerTask_LaunchWxaApp     W->>A: 启动小程序(无登录态)     A->>A: 微信登录     note over A: wx.login     A->>W: (自动)     W->>F: (自动)     F->>F: 用户刷脸登录     A->>A: 已登录     end     M->>W: 注销登录     note over M,W: IPCInvokerTask_Deauthorize

# 2. 带登录态的小程序,用户身份相关能力调用

  • 微信登录,获得 OpenID
  • 获取用户信息、手机号
  • 订阅消息
  • 转发小程序(依赖微信客户端功能,弹出二维码转至手机完成)
  • 免授权展示用户公开信息
  • 小程序使用记录同步至手机微信客户端(「最近使用」的小程序列表)

# 接口功能总览

# 0. WMPF 接口文档导览(GitHub Wiki

文档目录 刷脸支付设备的用法说明
Home 不适用,以本文档第二部分描述为准
硬件注册步骤 不适用,以本文档第二部分描述为准
硬件注册 For JVM (experimental) 不适用
人脸识别及支付相关文档 刷脸支付设备专用
Service 与 Client 的 IPC 交互协议 通用,主应用与 [WMPF] 的交互能力( Service 即 [WMPF],Client 即主应用)
WMPF 调用通道 (Invoke Channel) 通用,主应用与小程序的交互能力
WMPF 专有接口 (JSAPI) 通用,小程序在 [WMPF] 上的扩展能力
WMPF Push 能力 通用,触发主应用的消息推送能力
Q&A 通用,常见问答,建议阅读

# 1. 主应用与 [WMPF] 的交互

Service 与 Client 的 IPC 交互协议

# 激活设备
# 预置刷脸调用参数
# 请求用户授权登录,使 [WMPF] 获得用户的微信登录态
# 启动、关闭小程序
# 预加载
# 其他

# 2. 主应用与小程序的交互

WMPF 调用通道 (Invoke Channel)

主应用与小程序间可作本地双向通讯,通讯内容及格式可自定义

  • 主应用可借助小程序,拓展其微信生态连接能力
  • 小程序可借助主应用,拓展其硬件场景调用能力
  • 场景示例:
    • 小程序向主应用传递信息,如会员信息、手机号,在收银系统中完成会员登录
    • 小程序向主应用请求本地数据库的商品信息
    • 小程序向主应用发起外设调用请求,如打印
    • 主应用将外设的输入内容透传至小程序

# 3. 小程序的能力

# 刷脸支付硬件上的专有能力
  • 小程序运行中发起刷脸登录,仅当 [WMPF] 无登录态时适用
    • wx.login 接口触发。
    • 触发逻辑:
      • 由于 [WMPF] 无登录态,调用 wx.login 时无法正常返回用户信息,所以 [WMPF] 将自动请求用户登录,再执行常规的 wx.login
      • 若已前置执行 IPCInvokerTask_InitWxFacePayInfo 预置刷脸调用参数,优先调用刷脸登录;若刷脸失败或无预置刷脸调用参数,降级为调用二维码登录。
    • 截至 WMPF v1.0.3,在小程序生命周期内只可执行一次,无论是否登录成功。
  • 小程序运行中发起刷脸支付
    • 需前置执行 IPCInvokerTask_InitWxFacePayInfo 预置刷脸调用参数
    • 小程序调用 wmpf.wxFacePay.facePay 调起刷脸支付,获取付款码
# 手机微信客户端的通用能力

设备上可运行与手机微信客户端相同的小程序(AppID),并沿用手机微信客户端上的大部分能力,见:

当用户登录 [WMPF] 后,小程序便可获得与用户身份相关的能力,如:

  • 请求用户信息、手机号,订阅服务通知
  • 小程序使用记录会同步至手机微信客户端的「最近使用」小程序列表

# 4. 小程序审核Tips

在小程序提交正式版审核时,可参考以下建议,帮助小程序过审:

在备注中清晰说明:此小程序的哪个功能需要配合刷脸设备使用,无法在移动端体验

上传小程序在设备内使用流程的视频


# 第四部分 典型使用场景

# A. 收银流程中,启动小程序实现会员注册

商户 app → 刷脸登录,判断用户身份 → 启动小程序 → 请求用户信息、完成会员注册 → 回到收银流程

更多场景,持续更新。


上次更新: 12/21/2020, 12:37:59 PM