本文檔旨在介紹：以「SDK 模式」接入的多種刷臉支付設(shè)備上，如何開發(fā)、運(yùn)行小程序。

# 產(chǎn)品價(jià)值

小程序可以運(yùn)行在不同終端上。在手機(jī)微信客戶端或刷臉支付設(shè)備上運(yùn)行的小程序，本質(zhì)相同，有著相同的技術(shù)原理、帳號(hào)體系。在不同運(yùn)行環(huán)境，卻有部分能力差異，但更重要的是應(yīng)用場(chǎng)景的差異。例如：

• 從個(gè)人手機(jī)場(chǎng)景，到門店智能硬件的場(chǎng)景
• 從僅由用戶操作，到成為商家的經(jīng)營工具，由店員與顧客實(shí)時(shí)互動(dòng)
• 用戶在線下設(shè)備亦可臨時(shí)登錄微信身份，從而連接起物理世界與數(shù)字世界

刷臉支付設(shè)備運(yùn)行小程序，容易獲得以下特性：

• 連接微信

  微信身份（ 用戶帳號(hào)體系 / 用戶信息授權(quán) / 連接關(guān)系鏈）

  微信服務(wù)（訂閱服務(wù)通知 / 企微加群插件 / 電子發(fā)票… ）

• 多端融合

  跨終端 - 跨場(chǎng)景 - 線上線下：服務(wù)融合 流量互通

• 低成本開發(fā)運(yùn)維運(yùn)營

  開發(fā)簡單 / 敏捷更新 / 存量應(yīng)用遷移 / 用戶認(rèn)知成熟 / 易于傳播

以上可能帶來創(chuàng)新機(jī)會(huì)。如何連接微信，構(gòu)建多端融合的服務(wù)場(chǎng)景，值得思考探索。

# 關(guān)鍵概念

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

• 是微信客戶端之外的小程序運(yùn)行環(huán)境，由微信官方提供。為方便理解，可以將「小程序框架」與「小程序應(yīng)用」，類比為「瀏覽器」與「瀏覽器插件」的關(guān)系。
• [WMPF] 可廣泛通用于多種智能硬件，本身不限于刷臉支付設(shè)備使用。
• 在刷臉支付設(shè)備上使用 [WMPF]，相較于其他設(shè)備會(huì)有所不同（包括接入流程、部分接口設(shè)計(jì)），本文檔將作出說明。

# 文檔用法

1. 本文檔將介紹 [WMPF] 在刷臉支付設(shè)備上的使用方法，包括專用的接入流程及接口設(shè)計(jì)。若這部分內(nèi)容與 [WMPF] 的通用文檔描述有差異，請(qǐng)以本文檔為準(zhǔn)。
2. 除本文檔外，還有必要閱讀以下文檔，以完整了解本文檔所未涉及的通用能力、進(jìn)行通用功能開發(fā)：

• 刷臉支付接入指引
• 微信刷臉支付 SDK 開發(fā)文檔
• 微信小程序硬件框架通用文檔
• 微信小程序開發(fā)文檔

3. 如有疑問或困難，請(qǐng)前往：

• 刷臉支付常見問題
• 微信開放社區(qū) - 刷臉支付
• 微信開放社區(qū) - 小程序
• [WMPF]Q&A

# 適用條件

設(shè)備類型

• 暫只支持 Android 設(shè)備。
• 以「SDK 模式」接入刷臉支付的設(shè)備。

注：在「青蛙模式」中，青蛙 app 已集成小程序框架，只需開發(fā)小程序并在商戶平臺(tái)將其下發(fā)至設(shè)備運(yùn)行，見青蛙運(yùn)行小程序產(chǎn)品文檔。

• 【重要】 設(shè)備已完成軟硬件接入流程、已綁定「鋪設(shè)服務(wù)商」帳號(hào)（MchID）。

操作參考：設(shè)備關(guān)系綁定

必備應(yīng)用

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

建議由設(shè)備商將以上應(yīng)用預(yù)置在 ROM 中。

硬件配置要求

• CPU：四核 2 GHz 或以上
• 儲(chǔ)存：2GB RAM + 8GB ROM 或以上

# 第二部分 接入流程、權(quán)限注冊(cè)

本部分，將指引你使用刷臉支付設(shè)備接入 [WMPF] 并綁定所需運(yùn)行的小程序。

# 流程總覽

# 詳細(xì)說明

0. 以 鋪設(shè)服務(wù)商帳號(hào)(MchID) 登錄商戶平臺(tái)，進(jìn)入「刷臉SDK接入小程序框架」功能

1. 激活「微信終端合作平臺(tái)」帳號(hào)，自動(dòng)完成設(shè)備類型注冊(cè)，獲取 product_id 和 model_name。

2. 使用設(shè)備的主應(yīng)用（即商戶app）在微信開放平臺(tái)創(chuàng)建移動(dòng)應(yīng)用，獲取該移動(dòng)應(yīng)用的 AppID 即hostAppId，及AppSecret、access_token。

1. 開放平臺(tái)帳號(hào)，需完成企業(yè)主體認(rèn)證。
2. 創(chuàng)建移動(dòng)應(yīng)用一般需 7 天審核，請(qǐng)盡早申請(qǐng)。同一應(yīng)用 apk 只可以創(chuàng)建一個(gè)移動(dòng)應(yīng)用 AppID。
3. Android 應(yīng)用簽名生成工具

3. 綁定設(shè)備上的主應(yīng)用（即商戶app）所需運(yùn)行的小程序 AppID。

1. 此步驟僅為獲取小程序的運(yùn)行權(quán)限，調(diào)起行為由主應(yīng)用通過終端接口發(fā)起。
2. 主體限制：同一移動(dòng)應(yīng)用，可綁定無限個(gè)相同主體小程序、50 個(gè)非同主體小程序。

4. 設(shè)備注冊(cè)為后臺(tái)接口，詳見調(diào)用方法

1. 可在終端合作平臺(tái)的「查詢?cè)O(shè)備狀態(tài)」功能，檢查設(shè)備是否成功注冊(cè)。
2. 使用mmpayiotdevicemanagelogicsvrAPI，可從微信支付商戶平臺(tái)批量導(dǎo)出設(shè)備列表，其中
   • device_id 即「設(shè)備序列號(hào)(SN)」 。
   • model_name 即「設(shè)備型號(hào)」。

至此，接入流程完成。

特定設(shè)備（SN）、特定主應(yīng)用（AppID, 或稱 hostAppId ），將可調(diào)起 [WMPF] 運(yùn)行特定小程序（AppID）。

# 第三部分 接口功能、終端開發(fā)

本部分，將介紹 [WMPF] 在刷臉支付設(shè)備上的功能及調(diào)用方法，指引你完成主應(yīng)用和小程序的開發(fā)：

1. 主應(yīng)用
   • 承擔(dān)設(shè)備基礎(chǔ)功能的原生應(yīng)用，一般為收銀軟件，或稱為「商戶 app」。
   • 作為 [WMPF] 的調(diào)起方，需集成 [WMPF] 的 aar 并作接口開發(fā)。
   • 作為 刷臉支付 的調(diào)起方，需繼承 刷臉支付SDK 并做接口開發(fā)。
   • 商戶應(yīng)用示例源碼可以參考wmpf_demo，構(gòu)建模式需切換到wxfacepay。
2. 小程序
   • 由主應(yīng)用通過 [WMPF] 調(diào)起運(yùn)行，生命周期由主應(yīng)用控制（可在交互流程中臨時(shí)調(diào)起、使用后關(guān)閉；也可保持常駐運(yùn)行）。
   • 線上線下場(chǎng)景，可運(yùn)行相同的小程序（AppID）。可沿用手機(jī)微信客戶端上的大部分能力，也可使用基于硬件場(chǎng)景額外提供的能力。
   • 小程序示例源碼可以參考wxfacepay-wmpf-mp-demo。

# 使用示例

# 1. 小程序的兩種登錄、啟動(dòng)模式

• 先登錄再啟動(dòng)小程序
• 先啟動(dòng)小程序再登錄

# 2. 帶登錄態(tài)的小程序，用戶身份相關(guān)能力調(diào)用

• 微信登錄，獲得 OpenID
• 獲取用戶信息、手機(jī)號(hào)
• 訂閱消息
• 轉(zhuǎn)發(fā)小程序（依賴微信客戶端功能，彈出二維碼轉(zhuǎn)至手機(jī)完成）
• 免授權(quán)展示用戶公開信息
• 小程序使用記錄同步至手機(jī)微信客戶端（「最近使用」的小程序列表）

# 接口功能總覽

# 0. WMPF 接口文檔導(dǎo)覽（GitHub Wiki）

# 1. 主應(yīng)用與 [WMPF] 的交互

Service 與 Client 的 IPC 交互協(xié)議

# 激活設(shè)備

• IPCInvokerTask_ActivateDeviceByIoT // 刷臉支付設(shè)備專用
• IPCInvokerTask_NotifyActivateDevice
• IPCInvokerTask_ActivateDevice // 刷臉支付設(shè)備不適用

# 預(yù)置刷臉調(diào)用參數(shù)

• IPCInvokerTask_InitWxFacePayInfo // 傳入刷臉 SDK 的調(diào)用參數(shù)，是 [WMPF] 及小程序后續(xù)調(diào)用刷臉功能的前置條件

  • 參考刷臉 SDK「刷臉支付」 getWxpayfaceCode 的調(diào)用參數(shù)；注意參數(shù)的有效期，如 authinfo 的 expires_in 。

# 請(qǐng)求用戶授權(quán)登錄，使 [WMPF] 獲得用戶的微信登錄態(tài)

• IPCInvokerTask_AuthorizeByWxFacePay // 刷臉登錄

  • 用戶刷臉成功后，主應(yīng)用可獲得用戶信息，參考刷臉 SDK「人臉識(shí)別」 getWxpayfaceUserInfo 的返回參數(shù)。

• IPCInvokerTask_Authorize // 二維碼登錄

• IPCInvokerTask_Deauthorize // 注銷登錄態(tài)（將完全退出小程序）

• IPCInvokerTask_AuthorizeNoLogin // 接口將廢棄，如需以無登錄態(tài)啟動(dòng)小程序，直接啟動(dòng)即可，不必使用此接口

# 啟動(dòng)、關(guān)閉小程序

• IPCInvokerTask_LaunchWxaApp // 啟動(dòng)特定小程序

  • 注意：正式版小程序可以無登錄態(tài)啟動(dòng)；體驗(yàn)版、開發(fā)版，由于平臺(tái)需校驗(yàn)用戶權(quán)限，必須前置登錄才可以啟動(dòng)。

• IPCInvokerTask_LaunchWxaAppByQrCode

• IPCInvokerTask_CloseWxaApp // 關(guān)閉小程序（小程序退后臺(tái)）

# 預(yù)加載

• IPCInvokerTask_PreloadRuntime // 預(yù)加載小程序運(yùn)行環(huán)境，提升啟動(dòng)速度

• IPCInvokerTask_LaunchWxaApp // 傳入?yún)?shù)isForPreWarmLaunch=true可以預(yù)熱特定小程序

# 其他

• IPCInovkerTask_SetPushMsgCallback // 觸發(fā)主應(yīng)用的消息推送

  • 詳見 WMPF Push 能力
  • 場(chǎng)景示例：小程序后臺(tái)掛起后收到訂單，通過主應(yīng)用彈出消息提醒，點(diǎn)擊消息回到小程序

• IPCInvokerTask_ManageBackgroundMusic

• IPCInvokerTask_NotifyBackgroundMusic

# 2. 主應(yīng)用與小程序的交互

WMPF 調(diào)用通道 (Invoke Channel)

主應(yīng)用與小程序間可作本地雙向通訊，通訊內(nèi)容及格式可自定義

• 主應(yīng)用可借助小程序，拓展其微信生態(tài)連接能力
• 小程序可借助主應(yīng)用，拓展其硬件場(chǎng)景調(diào)用能力
• 場(chǎng)景示例：
  • 小程序向主應(yīng)用傳遞信息，如會(huì)員信息、手機(jī)號(hào)，在收銀系統(tǒng)中完成會(huì)員登錄
  • 小程序向主應(yīng)用請(qǐng)求本地?cái)?shù)據(jù)庫的商品信息
  • 小程序向主應(yīng)用發(fā)起外設(shè)調(diào)用請(qǐng)求，如打印
  • 主應(yīng)用將外設(shè)的輸入內(nèi)容透傳至小程序

# 3. 小程序的能力

# 刷臉支付硬件上的專有能力

• 小程序運(yùn)行中發(fā)起刷臉登錄，僅當(dāng) [WMPF] 無登錄態(tài)時(shí)適用
  • 由 wx.login 接口觸發(fā)。
  • 觸發(fā)邏輯：
    • 由于 [WMPF] 無登錄態(tài)，調(diào)用 wx.login 時(shí)無法正常返回用戶信息，所以 [WMPF] 將自動(dòng)請(qǐng)求用戶登錄，再執(zhí)行常規(guī)的 wx.login。
    • 若已前置執(zhí)行 IPCInvokerTask_InitWxFacePayInfo 預(yù)置刷臉調(diào)用參數(shù)，優(yōu)先調(diào)用刷臉登錄；若刷臉失敗或無預(yù)置刷臉調(diào)用參數(shù)，降級(jí)為調(diào)用二維碼登錄。
  • 截至 WMPF v1.0.3，在小程序生命周期內(nèi)只可執(zhí)行一次，無論是否登錄成功。
• 小程序運(yùn)行中發(fā)起刷臉支付
  • 需前置執(zhí)行 IPCInvokerTask_InitWxFacePayInfo 預(yù)置刷臉調(diào)用參數(shù)
  • 小程序調(diào)用 wmpf.wxFacePay.facePay 調(diào)起刷臉支付，獲取付款碼

# 手機(jī)微信客戶端的通用能力

設(shè)備上可運(yùn)行與手機(jī)微信客戶端相同的小程序（AppID），并沿用手機(jī)微信客戶端上的大部分能力，見：

• 微信小程序開發(fā)文檔
• 微信小程序硬件框架功能列表（見頁面底部的列表）
• 部分依賴手機(jī)客戶端環(huán)境而在 [WMPF] 上無法直接實(shí)現(xiàn)的能力，[WMPF] 將喚起二維碼，引導(dǎo)用戶掃碼回到手機(jī)上繼續(xù)操作

當(dāng)用戶登錄 [WMPF] 后，小程序便可獲得與用戶身份相關(guān)的能力，如：

• 請(qǐng)求用戶信息、手機(jī)號(hào)，訂閱服務(wù)通知
• 小程序使用記錄會(huì)同步至手機(jī)微信客戶端的「最近使用」小程序列表

# 4. 小程序?qū)徍薚ips

在小程序提交正式版審核時(shí)，可參考以下建議，幫助小程序過審：

在備注中清晰說明：此小程序的哪個(gè)功能需要配合刷臉設(shè)備使用，無法在移動(dòng)端體驗(yàn)

上傳小程序在設(shè)備內(nèi)使用流程的視頻

# 第四部分 典型使用場(chǎng)景

# A. 收銀流程中，啟動(dòng)小程序?qū)崿F(xiàn)會(huì)員注冊(cè)

商戶 app → 刷臉登錄，判斷用戶身份 → 啟動(dòng)小程序 → 請(qǐng)求用戶信息、完成會(huì)員注冊(cè) → 回到收銀流程

更多場(chǎng)景，持續(xù)更新。