# 二、人臉識別文檔
# 人臉識別場景說明
人臉識別通過識別用戶人臉,獲取用戶信息(openid)。
此功能常用于商戶會員、商品推薦等場景, 此流程無法用于支付。
FACEID-ONCE為直接啟動人臉識別流程。
# 接入過程
# 人臉識別FACEID-ONCE模式時序圖
# 公共響應(yīng)參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
# 公共錯誤碼
參數(shù) | 錯誤碼 | 類型 | 說明 |
---|---|---|---|
return_code | SUCCESS | string | 接口成功 |
return_code | ERROR | string | 接口失敗 |
return_code | PARAM_ERROR | string | 參數(shù)錯誤 |
return_code | SYSTEMERROR | string | 接口返回錯誤 |
# 二級錯誤碼
參數(shù) | 錯誤碼 | 類型 | 說明 |
---|---|---|---|
err_code | 271378620 | Interger | 刷臉服務(wù)未初始化,請調(diào)用初始化 |
err_code | 271378621 | Interger | 刷臉服務(wù)初始化中,等待500ms左右重新調(diào)用init |
# 接口調(diào)用流程
# 1、程序啟動時初始化
# 程序啟動時初始化initWxpayface
接口作用:對人臉SDK進行初始化
# 請求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
ip | 否 | string | HTTP代理IP或域名 |
port | 否 | string | HTTP代理端口, 須為數(shù)字 |
user | 否 | string | HTTP代理的用戶名 |
passwd | 否 | string | HTTP代理的密碼 |
proxy_type | 否 | int | 0:none; 1:HttpTunnel; 2:Socks5; 3:Http v2.12及以上 |
tcp_port | 否 | string | TCP的代理端口,如果TCP代理與IP代理同一端口,則無需設(shè)置v2.12及以上 |
perform_mode | 否 | string | NORMAL_PRFORM : 正常性能表現(xiàn); LOW_PERFORM : 低性能表現(xiàn) 默認(rèn)為正常性能表現(xiàn) v2.13及以上 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
# 請求示例
/**
* 初始化
*
*/
Map<String, String> m1 = new HashMap<>();
// m1.put("ip", "192.168.1.1"); //若沒有代理,則不需要此行
// m1.put("port", "8888");//若沒有代理,則不需要此行
// m1.put("user", mEtnUser.getText().toString());//若沒有代理,則不需要此行
// m1.put("passwd", mEtnPassword.getText().toString());//若沒有代理,則不需要此行
// m1.put("proxy_type", 1 ); //若沒有代理,則不需要此行
// m1.put("perform_mode", "LOW_PERFORM");//低性能表現(xiàn),默認(rèn)關(guān)閉美顏等
WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
建議:1、您可以自定義一個Application,然后在自定義Application的onCreate()中調(diào)用initPayFace()完成人臉識別模塊的初始化 2、您可以只在被調(diào)用人臉識別模塊的activity的onCreate()中完成initPayFace()的調(diào)用
注意:目前我們沒有在initPayFace()中做app保活的自啟措施,所以當(dāng)您的應(yīng)用在啟動過程中遇到重啟/更新的問題,您必須重新調(diào)用initPayFace(),相信我們會在下一個最新的版本中對initPayFace()做進一步的完善。
# 2、獲取數(shù)據(jù)
# 獲取數(shù)據(jù)getWxpayfaceRawdata
接口作用:獲取rawdata數(shù)據(jù)
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。用于接口調(diào)用, 參見: get_wxpayface_authinfo: rawdata |
# 請求示例
/**
* 獲取rawdata
*
*/
WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
String rawdata = info.get("rawdata");
}
});
注意:請在初始化(initWxpayface)成功后獲取數(shù)據(jù)(getWxpayfaceRawdata)
# 3、獲取調(diào)用憑證
# 獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)(獲取調(diào)用憑證)
接口作用:獲取調(diào)用憑證
接口地址:https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
# 請求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
store_id | 是 | string(32) | 門店編號, 由商戶定義, 各門店唯一。 |
store_name | 是 | string(128) | 門店名稱,由商戶定義。(可用于展示) |
device_id | 是 | string(32) | 終端設(shè)備編號,由商戶定義。 |
attach | 否 | string | 附加字段。字段格式使用Json |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。由微信人臉SDK的接口返回。 獲取方式參見: [獲取數(shù)據(jù) getWxpayfaceRawdata](#獲取數(shù)據(jù) getWxpayfaceRawdata) [獲取數(shù)據(jù) getWxpayfaceRawdata](#獲取數(shù)據(jù) getWxpayfaceRawdata) |
appid | 是 | string(32) | 商戶號綁定的公眾號/小程序 appid |
mch_id | 是 | string(32) | 商戶號 |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號/小程序 appid(服務(wù)商模式) |
sub_mch_id | 否 | string(32) | 子商戶號(服務(wù)商模式) |
now | 是 | int | 取當(dāng)前時間,10位unix時間戳。 例如:1239878956 |
version | 是 | string | 版本號。固定為1 |
sign_type | 是 | string | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 |
nonce_str | 是 | string(32) | 隨機字符串,不長于32位 |
sign | 是 | string | 參數(shù)簽名。詳見微信支付簽名算法 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string(16) | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
authinfo | 是 | string(4096) | SDK調(diào)用憑證。用于調(diào)用SDK的人臉識別接口。 參見[人臉識別 getWxpayfaceCode](#人臉識別 getWxpayfaceCode) |
expires_in | 否 | int | authinfo的有效時間, 單位秒。 例如: 3600 在有效時間內(nèi), 對于同一臺終端設(shè)備,相同的參數(shù)的前提下(如:相同的公眾號、商戶號、 門店編號等),可以用同一個authinfo,多次調(diào)用SDK的 getWxpayfaceCode 接口。 |
nonce_str | 是 | string(32) | 隨機字符串 |
sign | 是 | string(32) | 響應(yīng)結(jié)果簽名 |
appid | 是 | string(32) | 公眾號 |
mch_id | 否 | string(32) | 商戶號 |
sub_appid | 否 | string(32) | 子商戶公眾賬號ID(服務(wù)商模式) |
sub_mch_id | 是 | string(32) | 子商戶號(服務(wù)商模式) |
# 請求示例
<return_code>SUCCESS</return_code>
<return_msg>請求成功</return_msg>
<nonce_str>Tivppi4UXAbgLxk8e1Sij76YdowOFFii</nonce_str>
<sign>PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B</sign>
<appid>wx31fdaErqR31</appid>
<mch_id>12345689</mch_id>
<authinfo>q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04</authinfo>
<expires_in>7200</expires_in>
建議:返回的接口憑證authinfo
,可以在expires_in
指定的有效期內(nèi),同一臺機具上重復(fù)使用
注意:這是一個后端調(diào)用接口,請在獲取數(shù)據(jù)(getWxpayfaceRewdata)成功后獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)
# 4、獲取用戶信息
# 獲取用戶信息getWxpayfaceUserInfo(authinfo)
接口作用:通過人臉識別獲取用戶信息。
該接口與人臉識別 getWxpayfaceCode的區(qū)別:
- 無法用于訂單支付;
- UI交互不同。
**適用范圍:**適用于會員、推薦等場景。
# 請求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
appid | 是 | string | 商戶號綁定的公眾號/小程序 appid |
mch_id | 是 | string | 商戶號 |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號/小程序 appid(可不填) |
sub_mch_id | 否 | string(32) | 子商戶號(非服務(wù)商模式不填) |
store_id | 是 | string | 門店編號 |
face_authtype | 是 | string | 人臉識別模式。可選值:FACEID-ONCE : 人臉識別(單次模式)FACEID-LOOP : 人臉識別(循環(huán)模式) |
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
ask_unionid | 否 | string | 是否請求獲取union_id。可選值[0:不獲取;1:獲取]2.12新增 |
screen_index | 否 | string | 指定刷臉界面的運行屏幕,可選值:“0”, 運行在主屏; "1", 運行在 副屏; "2", 雙屏同顯; "3", 強制用presentation方式運行在副屏; "4", 副屏運行刷臉,主屏展示引導(dǎo)窗 |
overlay_option | 否 | string | 指定刷臉presentation界面的層級,可選值:“0”不強制指定層級(默認(rèn));"1"強制在其他應(yīng)用上層顯示; |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
openid | 是 | string | openid |
sub_openid | 否 | string | 子商戶號下的openid(服務(wù)商模式) |
nickname | 是 | string | 微信昵稱 |
token | 否 | string | 用于獲取union_id,獲取union_id文檔2.12新增 |
unionid_code | 否 | string | 獲取union_id 返回碼。公共定義見公共錯誤碼2.12新增 |
unionid_msg | 否 | string | 獲取union_id 返回信息,對unionid_code返回碼的描述2.12新增 |
# 請求示例
// 詳細(xì)的參數(shù)配置表可見上方的“接口參數(shù)表”
Map<String, String> m1 = new HashMap<String, String>();
m1.put("appid", "填您的公眾號"); // 公眾號,必填
m1.put("mch_id", "填您的商戶號"); // 商戶號,必填
// m1.put("sub_appid", "xxxxxxxxxxxxxx"); // 子商戶公眾賬號ID(非服務(wù)商模式不填)
// m1.put("sub_mch_id", "填您的子商戶號"); // 子商戶號(非服務(wù)商模式不填)
m1.put("store_id", "填您的門店編號"); // 門店編號,必填
m1.put("face_authtype", "FACEID-ONCE"); // 人臉識別模式, FACEID-ONCE`: 人臉識別(單次模式) FACEID-LOOP`: 人臉識別(循環(huán)模式), 必填
m1.put("authinfo", "填您的調(diào)用憑證"); // 調(diào)用憑證,詳見上方的接口參數(shù)
// m1.put("ask_unionid", "1"); // 是否獲取union_id 0:獲取 1:不獲取
WxPayFace.getInstance().getWxpayfaceUserInfo(m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
new RuntimeException("調(diào)用返回為空").printStackTrace();
return;
}
String code = (String) info.get("return_code"); // 錯誤碼
Integer errcode = (Integer) info.get("err_code"); // 二級錯誤碼
String msg = (String) info.get("return_msg"); // 錯誤碼描述
String openid = info.get("openid").toString(); // openid
String sub_openid = "";
if (info.get("sub_openid") != null) sub_openid = info.get("sub_openid").toString(); // 子商戶號下的openid(服務(wù)商模式)
String nickName = info.get("nickname").toString(); // 微信昵稱
String token = "";
if (info.get("token") != null) token = info.get("token").toString(); // facesid,用戶獲取unionid
if (code == null || openid == null || nickName == null || !code.equals("SUCCESS")) {
new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
return ;
}
/*
獲取union_id邏輯,傳入?yún)?shù)ask_unionid為"1"時使用
String unionid_code = "";
if (info.get("unionid_code") != null) unionid_code = info.get("unionid_code").toString();
if (TextUtils.equals(unionid_code,"SUCCESS")) {
//獲取union_id邏輯
} else {
String unionid_msg = "";
if (info.get("unionid_msg") != null) unionid_msg = info.get("unionid_msg").toString();
//處理返回信息
}
*/
/*
在這里處理您自己的業(yè)務(wù)邏輯
需要注意的是:
1、上述注釋中的內(nèi)容并非是一定會返回的,它們是否返回取決于相應(yīng)的條件
2、當(dāng)您確保要解開上述注釋的時候,請您做好空指針的判斷,不建議直接調(diào)用
*/
}
});
注意:請在獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)成功后調(diào)用獲取用戶信息getWxpayfaceUserInfo(authinfo);請不要直接在副屏presentation里調(diào)用。
# 5、釋放資源
# 釋放資源releaseWxpayface
接口作用:釋放人臉服務(wù),斷開連接。
接口使用規(guī)范:
- 聚合支付情況下:每次啟動刷臉都需要initWxpayface,刷臉結(jié)束后需要調(diào)用releaseWxpayface(釋放攝像頭供其他刷臉支付平臺調(diào)用);
- 非聚合支付情況下:首次刷臉需要initWxpayface,刷臉結(jié)束后不需要調(diào)用releaseWxpayface,否則下次刷臉需要重新initWxpayface,影響啟動耗時;初始化之后第二次刷臉可以直接調(diào)用getWxpayfaceCode啟動刷臉(在保證authinfo有效的情況下)。
# 請求示例
/**
*釋放資源
*
*/
WxPayFace.getInstance().releaseWxpayface(context);