# 離線刷臉開(kāi)發(fā)接入注意事項(xiàng)

# 1. [終端]離線刷臉SDK API調(diào)用注意事項(xiàng)

# 1.1 兼容人臉?lè)?wù)中斷的情況（看門(mén)狗機(jī)制）

人臉應(yīng)用升級(jí)時(shí)，需重新安裝，觸發(fā)人臉進(jìn)程重啟，從而導(dǎo)致服務(wù)中斷。
建議：

1. 人臉應(yīng)用OTA升級(jí)時(shí)，ROM不要拉起人臉應(yīng)用到前臺(tái)；
   
2. 主動(dòng)感知服務(wù)斷連，如：門(mén)禁長(zhǎng)時(shí)間無(wú)回調(diào)，接口調(diào)用無(wú)返回等。
   

影響：
團(tuán)餐場(chǎng)景，當(dāng)次刷臉體驗(yàn)中斷，重試可恢復(fù)；
門(mén)禁場(chǎng)景，連續(xù)識(shí)別，如果未感知到人臉?lè)?wù)銷(xiāo)毀，將導(dǎo)致業(yè)務(wù)中斷。

# 1.2 避免頻繁銷(xiāo)毀初始化人臉?lè)?wù)：initWxpayface/releaseWxpayface

注意事項(xiàng)

1. 初始化時(shí)機(jī)：建議在應(yīng)用啟動(dòng)時(shí)初始化。
   自定義商戶(hù)應(yīng)用Application，在Application#onCreate()中調(diào)用initWxpayface。
   影響：
   若等到使用才初始化，會(huì)導(dǎo)致第一次刷臉體驗(yàn)緩慢。
   

2. Context建議使用ApplicationContext，應(yīng)用存活期間，保持人臉?lè)?wù)連接。
   影響：
   如果使用Activity/Service作為context傳入，需要處理結(jié)合組件生命周期init/release人臉?lè)?wù)來(lái)處理內(nèi)存泄漏問(wèn)題。
   

3. 盡量不要調(diào)用releaseWxpayface，release接口會(huì)銷(xiāo)毀人臉?lè)?wù)，給下次初始化帶來(lái)不必要耗時(shí)。
   影響：
   a、release會(huì)導(dǎo)致人臉?lè)?wù)斷連，再連接需要耗時(shí)；
   b、頻繁init/release，會(huì)導(dǎo)致刷臉體驗(yàn)緩慢/卡頓。
   

# 1.3 有效期內(nèi)請(qǐng)緩存復(fù)用AuthInfo

注意事項(xiàng)

1. authInfo具有時(shí)效性 "expires_in"字段 （默認(rèn)3600，即1小時(shí)），在有效期內(nèi)，商戶(hù)不需要重復(fù)請(qǐng)求，建議商戶(hù)對(duì)authInfo進(jìn)行緩存，每1小時(shí)進(jìn)行更新。
   影響：如果每次刷臉都請(qǐng)求authInfo，引入不必要的網(wǎng)絡(luò)耗時(shí)，會(huì)導(dǎo)致刷臉體驗(yàn)緩慢/卡頓。
   

# 1.4 及時(shí)更新人臉特征庫(kù)：manualUpdateFaceDatas/getSdkInfo

注意事項(xiàng)

1. 建議商戶(hù)APP在人臉?lè)?wù)初始化完成后，盡快調(diào)用接口更新人臉數(shù)據(jù)。首次識(shí)別前，要求進(jìn)行一次特征更新（成功/失敗都可以），更新過(guò)程中，禁止用戶(hù)操作，等待回調(diào)再開(kāi)始操作。
   
2. 人臉?lè)?wù)會(huì)定時(shí)自動(dòng)觸發(fā)特征更新（90s/次），但不會(huì)觸發(fā)回調(diào)。
   
3. getSdkInfo 可以獲取最近一次更新時(shí)間，字段key為：“l(fā)ast_update_data_time”，服務(wù)商可定期自查上次更新時(shí)間，如果超過(guò)10分鐘沒(méi)更新，可能設(shè)備網(wǎng)絡(luò)出現(xiàn)異常，請(qǐng)及時(shí)處理。
   影響：
   如果不及時(shí)更新將影響業(yè)務(wù)可用性，剛錄入的新同學(xué)將無(wú)法識(shí)別，解約的舊同學(xué)可能還能繼續(xù)識(shí)別。
   

# 1.5 預(yù)加載/預(yù)打開(kāi)攝像頭：preloadSdkEnv

注意事項(xiàng)

1. 攝像頭啟動(dòng)、人臉特征加載會(huì)有一定耗時(shí)，提前preloadsdkenv加載資源，可以保證第一次開(kāi)啟攝像頭和識(shí)別啟動(dòng)很快；
   影響：一般場(chǎng)景下，只有首次刷臉打開(kāi)攝像頭會(huì)比較慢。
   VoIP場(chǎng)景/聚合支付：如果攝像頭釋放了，再次重新打開(kāi)需1～2s，會(huì)導(dǎo)致刷臉緩慢。
   

# 1.6 設(shè)置刷臉預(yù)覽：setCameaPreview

注意事項(xiàng)

1. surface不能為空，surface銷(xiāo)毀后需要重新綁定；
   
2. surfaceView推薦全局使用同一個(gè)實(shí)例；
   
3. 綁定最佳時(shí)機(jī)為surfaceview不會(huì)再發(fā)生大小改變或者隱藏的時(shí)刻，避免需要?jiǎng)討B(tài)適配；
   
4. 默認(rèn)畫(huà)面為480x640，沒(méi)有比例限制，推薦按照3:4的長(zhǎng)寬比顯示，從而擴(kuò)大預(yù)覽范圍，方便適配豎版攝像頭，避免不同身高用戶(hù)需要彎腰墊腳；
   
5. 盡量在surfaceview大小確定以后再進(jìn)行調(diào)度，避免出現(xiàn)時(shí)序不當(dāng)問(wèn)題。
   影響：
   銷(xiāo)毀未重綁定/綁定后不斷改變大小導(dǎo)致時(shí)序不當(dāng)，可能導(dǎo)致surface渲染白屏。
   

# 1.7 刷臉識(shí)別流程：startVerify/stopVerify/finishFaceVerify/getFacePayCredential

注意事項(xiàng)

1. 接口分為開(kāi)始/停止，識(shí)別成功后自動(dòng)停止，而識(shí)別失敗會(huì)返回錯(cuò)誤碼并且自動(dòng)重新開(kāi)始識(shí)別，建議自行設(shè)置最長(zhǎng)超時(shí)實(shí)踐，推薦40s；
   
2. 識(shí)別成功返回的userInfo類(lèi)型，需要防止混淆，在proguard里需要keep對(duì)應(yīng)的class。
   

-keep class com.tencent.wxpayface.data.UserInfo{ *; }；

3. startFaceVerify 調(diào)用前必須更新人臉特征數(shù)據(jù)；
   
4. 識(shí)別成功后注意判斷“need_ext_verify”字段，確認(rèn)是否需要輔助驗(yàn)證。
   

時(shí)序要求

1. 正常支付流程，需要以獲取支付憑證(getFacePayCredential)作為支付標(biāo)準(zhǔn)終點(diǎn)；
   
2. 異常支付流程（取消/失敗），請(qǐng)不要調(diào)用(getFacePayCredential)，以免干擾支付側(cè)流失率統(tǒng)計(jì)。
   影響：調(diào)用不規(guī)范會(huì)導(dǎo)致支付告警誤報(bào)，無(wú)法更好的幫助商戶(hù)提升刷臉體驗(yàn)。
   

錯(cuò)誤案例
● 沒(méi)有得到識(shí)別回調(diào)就調(diào)用finishFaceVerify，此時(shí)流程報(bào)錯(cuò)“沒(méi)有用戶(hù)信息”，等到識(shí)別回調(diào)成功后，再次調(diào)用finishFaceVerify->getFacePayCredential，此時(shí)支付流程正常。
分析：第一次報(bào)錯(cuò)，支付側(cè)會(huì)認(rèn)為用戶(hù)刷臉失敗，用戶(hù)流失。
實(shí)際上用戶(hù)可以正常支付。

● 沒(méi)有調(diào)用finishFaceVerify時(shí)，就調(diào)用getFacePayCredential，此時(shí)報(bào)錯(cuò)“userId 為空”。后面調(diào)用正確，此時(shí)支付流程正常。
分析：第一次報(bào)錯(cuò)，支付側(cè)會(huì)認(rèn)為用戶(hù)刷臉失敗，用戶(hù)流失。
實(shí)際上用戶(hù)可以正常支付。

流程參考

標(biāo)準(zhǔn)時(shí)序：
startFaceVerify -> 識(shí)別回調(diào) -> (輔助驗(yàn)證) -> finishFaceVerify -> getFacePayCredential

中斷邏輯：
stopFaceVerify 僅停止渲染及識(shí)別，不會(huì)清除識(shí)別數(shù)據(jù)，支持任意時(shí)刻調(diào)用，停止之后請(qǐng)勿繼續(xù)調(diào)用。

# 1.8 定期重啟機(jī)制

為避免設(shè)備運(yùn)行時(shí)間過(guò)長(zhǎng)導(dǎo)致突發(fā)異常，建議非高峰期定期重啟，推薦1～3點(diǎn)，凌晨1點(diǎn)前作為升級(jí)時(shí)間。

影響：長(zhǎng)時(shí)間不重啟，擔(dān)心商戶(hù)APP/人臉?lè)?wù)/系統(tǒng)/攝像頭等多因素出現(xiàn)未知異常。

# 2. [后端]離線刷臉商戶(hù)接入常用接口調(diào)用注意事項(xiàng)

# 2.1 獲取憑證授權(quán)接口

POST https://api.mch.weixin.qq.com/v3/offlinefacemch/tokens

注意事項(xiàng)：
指定銀行卡簽約，用戶(hù)簽約時(shí)攜帶的token請(qǐng)使用預(yù)簽約接口獲取，該接口不支持指定卡簽約。

# 2.2 刷臉用戶(hù)信息修改接口

PATCH https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations/{organization_id}/users/out-user-id/{out_user_id}

注意事項(xiàng)：
若修改了學(xué)生姓名、班級(jí)、手機(jī)號(hào)時(shí)，需調(diào)用接口同步給微信側(cè)，否則可能導(dǎo)致小助手上記錄欠款的學(xué)生姓名、班級(jí)與實(shí)際不符合以及學(xué)生刷臉驗(yàn)證手機(jī)號(hào)時(shí)無(wú)法通過(guò)。

# 2.3 獲取authinfo接口

POST https://api.mch.weixin.qq.com/v3/offlineface/authinfo

注意事項(xiàng)：
建議authinfo每1小時(shí)內(nèi)獲取一次，否則當(dāng)設(shè)備斷網(wǎng)且恰好authinfo過(guò)期，則會(huì)導(dǎo)致設(shè)備不可用。
請(qǐng)求參數(shù)機(jī)構(gòu)ID字段，創(chuàng)建機(jī)構(gòu)的商戶(hù)號(hào)和mch_id應(yīng)該保持一致，否則無(wú)法獲取authinfo。

# 2.4 預(yù)簽約接口

POST https://api.mch.weixin.qq.com/v3/offlineface/contracts/presign

注意事項(xiàng)：

1. 一鍵綁卡不是支持所有銀行卡，上線前請(qǐng)先測(cè)試是否支持該銀行卡；
   
2. 建議上線前一周完成調(diào)試；
   
3. 簽約完成務(wù)必多次扣款，防止由于銀行限制每日扣款次數(shù)、扣款金額等影響用戶(hù)消費(fèi)；
   
4. 指定卡簽約建議異步扣款，否則銀行維護(hù)會(huì)導(dǎo)致不能扣費(fèi)，影響學(xué)生吃飯。
   

# 2.5 申請(qǐng)扣款接口

POST https://api.mch.weixin.qq.com/v3/offlineface/transactions

注意事項(xiàng)：
返回碼處理建議

# 2.6 其他

out_user_id：刷臉用戶(hù)標(biāo)識(shí)，需要商戶(hù)保證同一個(gè)刷臉用戶(hù)在一個(gè)機(jī)構(gòu)下唯一, 不要給同一個(gè)用戶(hù)創(chuàng)建多個(gè)out_user_id, 否則用戶(hù)會(huì)無(wú)法使用(即便前一個(gè)已經(jīng)解約也不行)。