关闭
公众号二维码

# 离线刷脸开发接入注意事项

# 1. [终端]离线刷脸SDK API调用注意事项

# 1.1 兼容人脸服务中断的情况(看门狗机制)

人脸应用升级时,需重新安装,触发人脸进程重启,从而导致服务中断。
建议

  1. 人脸应用OTA升级时,ROM不要拉起人脸应用到前台;
  2. 主动感知服务断连,如:门禁长时间无回调,接口调用无返回等。

影响
团餐场景,当次刷脸体验中断,重试可恢复
门禁场景,连续识别,如果未感知到人脸服务销毁,将导致业务中断

# 1.2 避免频繁销毁初始化人脸服务:initWxpayface/releaseWxpayface

注意事项

  1. 初始化时机:建议在应用启动时初始化
    自定义商户应用Application,在Application#onCreate()中调用initWxpayface。
    影响
    若等到使用才初始化,会导致第一次刷脸体验缓慢

  2. Context建议使用ApplicationContext,应用存活期间,保持人脸服务连接。
    影响
    如果使用Activity/Service作为context传入,需要处理结合组件生命周期init/release人脸服务来处理内存泄漏问题。

  3. 尽量不要调用releaseWxpayface,release接口会销毁人脸服务,给下次初始化带来不必要耗时。
    影响
    a、release会导致人脸服务断连,再连接需要耗时;
    b、频繁init/release,会导致刷脸体验缓慢/卡顿

# 1.3 有效期内请缓存复用AuthInfo

注意事项

  1. authInfo具有时效性 "expires_in"字段 (默认3600,即1小时),在有效期内,商户不需要重复请求,建议商户对authInfo进行缓存,每1小时进行更新。
    影响如果每次刷脸都请求authInfo,引入不必要的网络耗时,会导致刷脸体验缓慢/卡顿。

# 1.4 及时更新人脸特征库:manualUpdateFaceDatas/getSdkInfo

注意事项

  1. 建议商户APP在人脸服务初始化完成后,尽快调用接口更新人脸数据。首次识别前,要求进行一次特征更新(成功/失败都可以),更新过程中,禁止用户操作,等待回调再开始操作。
  2. 人脸服务会定时自动触发特征更新(90s/次),但不会触发回调
  3. getSdkInfo 可以获取最近一次更新时间,字段key为:“last_update_data_time”,服务商可定期自查上次更新时间,如果超过10分钟没更新,可能设备网络出现异常,请及时处理。
    影响
    如果不及时更新将影响业务可用性,刚录入的新同学将无法识别,解约的旧同学可能还能继续识别。

# 1.5 预加载/预打开摄像头:preloadSdkEnv

注意事项

  1. 摄像头启动、人脸特征加载会有一定耗时,提前preloadsdkenv加载资源,可以保证第一次开启摄像头和识别启动很快;
    影响:一般场景下,只有首次刷脸打开摄像头会比较慢。
    VoIP场景/聚合支付如果摄像头释放了,再次重新打开需1~2s,会导致刷脸缓慢。

# 1.6 设置刷脸预览:setCameaPreview

注意事项

  1. surface不能为空,surface销毁后需要重新绑定
  2. surfaceView推荐全局使用同一个实例
  3. 绑定最佳时机为surfaceview不会再发生大小改变或者隐藏的时刻,避免需要动态适配;
  4. 默认画面为480x640,没有比例限制,推荐按照3:4的长宽比显示,从而扩大预览范围,方便适配竖版摄像头,避免不同身高用户需要弯腰垫脚;
  5. 尽量在surfaceview大小确定以后再进行调度,避免出现时序不当问题。
    影响
    销毁未重绑定/绑定后不断改变大小导致时序不当,可能导致surface渲染白屏

# 1.7 刷脸识别流程:startVerify/stopVerify/finishFaceVerify/getFacePayCredential

注意事项

  1. 接口分为开始/停止,识别成功后自动停止,而识别失败会返回错误码并且自动重新开始识别,建议自行设置最长超时实践,推荐40s;
  2. 识别成功返回的userInfo类型,需要防止混淆,在proguard里需要keep对应的class
-keep class com.tencent.wxpayface.data.UserInfo{ *; }
  1. startFaceVerify 调用前必须更新人脸特征数据;
  2. 识别成功后注意判断“need_ext_verify”字段,确认是否需要辅助验证。

时序要求

  1. 正常支付流程,需要以获取支付凭证(getFacePayCredential)作为支付标准终点
  2. 异常支付流程(取消/失败),请不要调用(getFacePayCredential),以免干扰支付侧流失率统计。
    影响调用不规范会导致支付告警误报,无法更好的帮助商户提升刷脸体验。

错误案例
没有得到识别回调就调用finishFaceVerify,此时流程报错“没有用户信息”,等到识别回调成功后,再次调用finishFaceVerify->getFacePayCredential,此时支付流程正常。
分析:第一次报错,支付侧会认为用户刷脸失败,用户流失
实际上用户可以正常支付

● 没有调用finishFaceVerify时,就调用getFacePayCredential,此时报错“userId 为空”。后面调用正确,此时支付流程正常。
分析:第一次报错,支付侧会认为用户刷脸失败,用户流失
实际上用户可以正常支付

流程参考

标准时序:
startFaceVerify -> 识别回调 -> (辅助验证) -> finishFaceVerify -> getFacePayCredential

中断逻辑:
stopFaceVerify 仅停止渲染及识别,不会清除识别数据,支持任意时刻调用,停止之后请勿继续调用。

# 1.8 定期重启机制

为避免设备运行时间过长导致突发异常,建议非高峰期定期重启,推荐1~3点,凌晨1点前作为升级时间。

影响:长时间不重启,担心商户APP/人脸服务/系统/摄像头等多因素出现未知异常

# 2. [后端]离线刷脸商户接入常用接口调用注意事项

# 2.1 获取凭证授权接口

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

注意事项
指定银行卡签约,用户签约时携带的token请使用预签约接口获取,该接口不支持指定卡签约

# 2.2 刷脸用户信息修改接口

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

注意事项
若修改了学生姓名、班级、手机号时,需调用接口同步给微信侧,否则可能导致小助手上记录欠款的学生姓名、班级与实际不符合以及学生刷脸验证手机号时无法通过。

# 2.3 获取authinfo接口

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

注意事项
建议authinfo每1小时内获取一次,否则当设备断网且恰好authinfo过期,则会导致设备不可用。
请求参数机构ID字段,创建机构的商户号和mch_id应该保持一致,否则无法获取authinfo

# 2.4 预签约接口

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

注意事项

  1. 一键绑卡不是支持所有银行卡,上线前请先测试是否支持该银行卡;
  2. 建议上线前一周完成调试;
  3. 签约完成务必多次扣款,防止由于银行限制每日扣款次数、扣款金额等影响用户消费;
  4. 指定卡签约建议异步扣款,否则银行维护会导致不能扣费,影响学生吃饭。

# 2.5 申请扣款接口

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

注意事项
返回码处理建议

httpcode 错误码 处理方式
200 请求正确处理,应该判断订单状态 “SUCCESS”-支付成功(支付成功无需处理)
“REFUND"-转入退款(支付成功无需处理)
“NOTPAY”-未支付(24小时内参数不变重试扣款)
“CLOSED"-已关闭(参数不变换单号重试)
“REVOKED”-已撤销(参数不变换单号重试)
“USERPAYING”-用户支付中(24小时内参数不变重试扣款)
“PAYERROR”-支付失败(换单号重试)
500 SYSTEM_ERROR 请稍后重试,建议同一笔订单每天重试不要超过5次,频繁重试会导致该用户无法扣款
400 PARAM_ERROR 参数错误,请检查参数
400 INVALID_REQUEST 目前子商户未开通权限、凭证已经使用过并且扣款成功、请求参数和凭证信息不一致、凭证正在扣款又换单号重试、重入请求变更了参数都会返回该错误码,表示请求参数符合格式,但不符合业务规则,需要服务商定位问题并修正代码
429 RATELIMIT_EXCEEDED 请求达到速率限制

# 2.6 其他

out_user_id:刷脸用户标识,需要商户保证同一个刷脸用户在一个机构下唯一, 不要给同一个用户创建多个out_user_id, 否则用户会无法使用(即便前一个已经解约也不行)。

上次更新: 11/14/2022, 3:01:17 PM