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

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

# 产品价值

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

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

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

• 连接微信

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

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

• 多端融合

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

• 低成本开发运维运营

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

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

# 关键概念

微信小程序硬件框架（ Wechat Mini-Program Framework，简称小程序框架或 [WMPF] ）

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

# 文档用法

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

• 刷脸支付接入指引
• 微信刷脸支付 SDK 开发文档
• 微信小程序硬件框架通用文档
• 微信小程序开发文档

3. 如有疑问或困难，请前往：

• 刷脸支付常见问题
• 微信开放社区 - 刷脸支付
• 微信开放社区 - 小程序
• [WMPF]Q&A

# 适用条件

设备类型

• 暂只支持 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] 并绑定所需运行的小程序。

# 流程总览

# 详细说明

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

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

2. 使用设备的主应用（即商户app）在微信开放平台创建移动应用，获取该移动应用的 AppID 即hostAppId，及AppSecret、access_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. 小程序的两种登录、启动模式

• 先登录再启动小程序
• 先启动小程序再登录

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

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

# 接口功能总览

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

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

Service 与 Client 的 IPC 交互协议

# 激活设备

• IPCInvokerTask_ActivateDeviceByIoT // 刷脸支付设备专用
• IPCInvokerTask_NotifyActivateDevice
• IPCInvokerTask_ActivateDevice // 刷脸支付设备不适用

# 预置刷脸调用参数

• IPCInvokerTask_InitWxFacePayInfo // 传入刷脸 SDK 的调用参数，是 [WMPF] 及小程序后续调用刷脸功能的前置条件

  • 参考刷脸 SDK「刷脸支付」 getWxpayfaceCode 的调用参数；注意参数的有效期，如 authinfo 的 expires_in 。

# 请求用户授权登录，使 [WMPF] 获得用户的微信登录态

• IPCInvokerTask_AuthorizeByWxFacePay // 刷脸登录

  • 用户刷脸成功后，主应用可获得用户信息，参考刷脸 SDK「人脸识别」 getWxpayfaceUserInfo 的返回参数。

• IPCInvokerTask_Authorize // 二维码登录

• IPCInvokerTask_Deauthorize // 注销登录态（将完全退出小程序）

• IPCInvokerTask_AuthorizeNoLogin // 接口将废弃，如需以无登录态启动小程序，直接启动即可，不必使用此接口

# 启动、关闭小程序

• IPCInvokerTask_LaunchWxaApp // 启动特定小程序

  • 注意：正式版小程序可以无登录态启动；体验版、开发版，由于平台需校验用户权限，必须前置登录才可以启动。

• IPCInvokerTask_LaunchWxaAppByQrCode

• IPCInvokerTask_CloseWxaApp // 关闭小程序（小程序退后台）

# 预加载

• IPCInvokerTask_PreloadRuntime // 预加载小程序运行环境，提升启动速度

• IPCInvokerTask_LaunchWxaApp // 传入参数isForPreWarmLaunch=true可以预热特定小程序

# 其他

• IPCInovkerTask_SetPushMsgCallback // 触发主应用的消息推送

  • 详见 WMPF Push 能力
  • 场景示例：小程序后台挂起后收到订单，通过主应用弹出消息提醒，点击消息回到小程序

• IPCInvokerTask_ManageBackgroundMusic

• IPCInvokerTask_NotifyBackgroundMusic

# 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] 上无法直接实现的能力，[WMPF] 将唤起二维码，引导用户扫码回到手机上继续操作

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

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

# 4. 小程序审核Tips

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

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

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

# 第四部分 典型使用场景

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

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

更多场景，持续更新。