本文為您介紹微信小程序接入圖形認證的集成方法和相關接口說明。
準備工作
環境要求
開發者工具 | 微信開發者工具 |
調試基礎庫 | 2.10.4及以上 |
下載SDK
登錄號碼認證產品控制臺,在概覽頁面右側API&SDK區域,單擊立即下載,進入API&SDK頁面,根據頁面提示下載并解壓對應SDK。
示例Demo
同時為您提供圖形認證功能微信小程序接入Demo,您可參考Demo示例代碼快速了解接入步驟。Demo下載請參見微信小程序接入Demo。
創建認證方案
登錄號碼認證產品控制臺。
在左側導航欄選擇融合認證(基于原子能力)> 圖形認證服務 > 圖形認證方案管理。
在圖形認證方案管理頁面,單擊新增圖形認證方案。
輸入方案名稱,接入端選擇H5,創建圖形認證方案,獲取密鑰參數(包括
appId
、appKey
)。說明接入端選擇只用于標記,不影響方案號使用。
接入步驟
引入組件
小程序后臺域名白名單添加合法域名
https://captcha.alicaptcha.com
。在需要驗證的頁面下的
xxxx.json
文件中引入要使用的組件,示例代碼如下,具體可參見Demo中的index.json
:{ "usingComponents": { "captcha4": "/component/captcha4/captcha4" } }
初始化
在需要驗證的頁面下 xxxx.wxml
文件中引入要使用的組件,示例參數為必傳。
<captcha4 id="captcha" wx:if="{{loadCaptcha}}" captchaId="{{captchaId}}" />
組件參數說明:
參數 | 是否必填 | 類型 | 說明 |
captchaId | 是 | string | 驗證碼ID,即在控制臺創建認證方案后獲取的 |
language | 否 | string | 指定語言,默認值:zh。 |
useNativeButton | 否 | boolean | 是否使用喚醒按鈕,取值:
|
riskType | 否 | string | 當服務端配置了結合風控融合,此字段可指定驗證形式。 重要 由于目前暫未提供風控融合模式,此參數調用不會生效。 |
hideBar | 否 | array | 隱藏后續驗證界面的關閉按鈕、刷新按鈕。可選值close/refresh。 |
scale | 否 | number | 縮放比例,默認值:1。 |
mask | 否 | object | 配置點擊驗證碼區域外是否關閉驗證,彈窗背景色。默認值: |
hideSuccess | 否 | boolean | 是否隱藏bind模式下的成功彈窗,默認值:false。 |
下面為事件監聽綁定示例,完整的事件說明及代碼示例請參見下文事件說明。
<captcha4
id="captcha"
wx:if="{{loadCaptcha}}"
captchaId="{{captchaId}}"
bindSuccess="captchaSuccess"
bindReady="captchaReady"
bindClose="captchaClose"
bindError="captchaError"
bindFail="captchaFail"
/>
無按鈕模式下,需要手動調用驗證碼的showCaptcha
方法拉起圖形驗證,示例代碼如下,具體可參見Demo中的index.js
。
const captcha = this.selectComponent('#captcha');
captcha.showCaptcha();
獲取成功憑證
成功完成驗證碼后,會觸發用戶自定義的 captchaSuccess 函數,將驗證結果存儲在 result(用戶可?定義保存?式),等待?次驗證時提取上傳,?按鈕模式時可以直接在此處進??次驗證。
captchaSuccess: function(result) {
console.log("captcha-Success!");
this.setData({
result: result.detail
})
}
提交二次校驗
用戶點擊提交按鈕觸發提交,進行二次驗證。
captchaValidate: function() {
var self = this;
var data = self.data.result; // 獲取完成驗證碼時存儲的驗證結果
if (typeof data !== 'object') {
console.log("請先完成驗證!");
return;
}
// 將結果提交給用戶服務端進行二次驗證
wx.request({
url: "用戶業務接口", // 替換為實際的URL
method: 'POST',
dataType: 'json',
data: Object.assign({}, data, {
captcha_id: self.data.captchaId
}),
success: function(res) {
wx.showToast({
title: res.data.result
});
},
fail: function() {
console.log('error');
}
});
}
事件說明
微信小程序事件通訊中固定存在一個對象event,組件返回的值位于該對象的detail屬性中,以下回調參數表示detail中值。
bindReady
監聽驗證按鈕的DOM生成完畢事件。
// wxml
<captcha4 bindReady="captchaReady"/>
// js
captchaReady: function () {
console.log('captcha-Ready!')
}
bindError
監聽驗證出錯事件,例如刷新過多、靜態資源加載失敗、網絡不暢通等驗證碼能捕獲到的錯誤,都會觸發Error回調,示例代碼如下: Error 返回一個 e,其中 e.detail 包含 2 個屬性:code(錯誤碼)、tips(錯誤提示)。
// wxml
<captcha4 bindError="captchaError"/>
// js
captchaError: function (e) {
console.log('captcha-Error!', e.detail)
}
bindSuccess
監聽驗證成功事件,返回一個result對象,result中的detail包含四個屬性:lot_number、pass_token、captcha_output、gen_time,這些參數為當前驗證成功的憑據,二次驗證時需要傳入。
// wxml
<captcha4 bindSuccess="captchaSuccess"/>
// js
captchaSuccess: function (result) {
console.log('captcha-Success!')
// 這里先將result中的參數保存,待進行二次驗證時傳入
this.setData({
result: result.detail
})
}
bindClose
用戶關閉彈出來的驗證時,會觸發該回調。
// wxml
<captcha4 bindClose="captchaClose"/>
// js
captchaClose: function () {
console.log('captcha-Close!')
}
bindFail
監聽驗證失敗的事件。
// wxml
<captcha4 bindFail="captchaFail"/>
// js
captchaFail: function () {
console.log('captcha-Fail!')
}
調用方法
方法名 | 說明 |
showCaptcha | 僅當useNativeButton值為false時調用,可喚起驗證碼彈窗。 |
reset | 重置驗證碼。 |
異常情況(宕機)說明
如果因為客戶端網絡或其他問題導致驗證碼初始化時無法訪問服務器,則進入宕機流程,宕機時驗證碼表現為立即通過,即時觸發Success事件。以上文的bindSuccess
為例,e.detail對象中會有lot_number
、pass_token
、captcha_output
、gen_time
、offline
,此時offline
值固定為true
。