本文中含有需要您注意的重要提示信息,忽略該信息可能對您的業務造成影響,請務必仔細閱讀。
本文介紹H5網頁端集成流程。
集成須知
瀏覽器兼容性
瀏覽器名稱 | Android版本 | iOS版本 |
Edge | Android 4.0及以上版本 | iOS 14.3及以上版本 |
FireFox | ||
Chrome | ||
Opera | ||
百度 | ||
Android Browser 5.0+ | ||
Safari | 不支持 | iOS 11及以上版本 |
UC | Android 4.0及以上版本 | 不支持 |
UC極速瀏覽器 | ||
廠商內置瀏覽器 | 小米、三星等部分機型支持 |
受制于瀏覽器兼容性碎片化問題,建議您在流程設計上引導用戶使用推薦的瀏覽器完成認證。若您在手機應用App內集成該方案,可能會因為內嵌瀏覽器原因無法兼容,您可以參考App內集成H5移動端SDK兼容性配置減少兼容性問題或集成Native SDK。若您是通過微信公眾號或者小程序集成,由于微信運營審核規則的限制,可能出現無法避免的兼容性問題,建議您使用純服務端(API)接入方式。
認證頁面
掃臉認證
為了提升用戶刷臉認證體驗,URL默認自帶掃臉認證引導頁,用戶同意認證后可以開始使用掃臉認證服務。微信公眾號場景下,掃臉認證引導頁是必須存在的,否則會導致攝像頭無法喚起,引發黑屏現象。
掃臉認證當前不支持自定義主題色,如需設置主題色,建議您集成SDK或API,自行封裝處理。
認證觸發頁面(啟動刷臉)
在代碼中引入如下JS文件,并調用函數
getMetaInfo()
獲取MetaInfo。<script type="text/javascript" src="https://o.alicdn.com/yd-cloudauth/cloudauth-cdn/jsvm_all.js" ></script>
警告在調用實人認證服務端發起認證請求時需要傳入獲取的MetaInfo值。
MetaInfo會隨著瀏覽器和設備的變化而變化,即使是在測試時也要實時傳入服務端接口,不要使用硬編碼的測試數據,否則很可能無法獲取CertifyUrl。
調用前面已經集成好的金融級實人認證服務端初始化接口,獲取CertifyUrl,并在瀏覽器中加載該鏈接進行實人認證。服務端如何發起認證請求,請參見服務端集成。
重要初始化接口返回的認證CertifyUrl在30分鐘有效且僅能認證提交一次,請您在有效期內使用,避免重復使用。
代碼示例
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Title</title>
<!-- 引入該JS,全局注入getMetaInfo方法 -->
<script type="text/javascript" src="https://o.alicdn.com/yd-cloudauth/cloudauth-cdn/jsvm_all.js" ></script>
</head>
<body>
<div></div>
<script>
// 在調用實人認證服務端發起認證請求時需要傳入該MetaInfo值
let MetaInfo = window.getMetaInfo();
// 請求認證業務接口獲取CertifyUrl
fetch('http://認證初始化接口地址', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(MetaInfo)
})
.then(response => response.json())
.then(data => {
console.log('data:', data)
// 獲取CertifyUrl后跳轉至認證頁面
window.location.href = data.resultObject.certifyUrl;
});
</script>
</body>
</html>
結果顯示頁面(結果解析)
CertifyUrl中ReturnUrl參數為商戶自定義參數,認證結果會在掃臉認證完成后拼接在ReturnUrl后作為參數返回給商戶。由于您傳入路由方式的可能不同,因此response解析結果會有差異。
路由模式 | ReturnUrl示例 | 認證后打開的ReturnUrl示例 |
普通網頁 | https://aliyundoc.com | https://aliyundoc.com/?response=%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D |
https://aliyundoc.com/index.html | https://aliyundoc.com/index.html?response=%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D | |
history不帶錨點 | https://aliyundoc.com/xxx/ | https://aliyundoc.com/xxx?response=%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D |
history帶錨點 | https://aliyundoc.com/xxx/#xxx | https://aliyundoc.com/xxx?response=%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D#xxx |
hash | https://aliyundoc.com/#/aaa/bbb | https://aliyundoc.com/?response=%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D/#/aaa/bbb |
hash路由和history原理介紹,請參見淺談前端路由原理hash和history。
代碼示例
認證結束后,頁面會跳轉至調用InitFaceVerify接口
時傳入的ReturnUrl
(結果顯示頁面)并攜帶認證結果數據。
如果需要二次驗證來預防盜鏈和篡改的風險,可以在解析結果后向服務端發起獲取最終驗證結果的請求,參見DescribeFaceVerify-獲取認證詳細數據。
下面的代碼簡要展示了不同路由形式的結果顯示頁面解析認證結果數據的過程。
普通網頁
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Title</title>
</head>
<body>
<script>
// 此時的window.location.href就是ReturnUrl了。
// 格式為:https://aliyundoc.com 或 https://aliyundoc.com/index.html
let url = new URL(window.location.href);
// 獲取返回的認證結果數據。
let parms = url.searchParams.get('response')
console.log('parms:', parms)
// 如果需要二次驗證實人認證結果可參考下面代碼。
// 獲取CertifyId 為了避免盜鏈和篡改風險,請自行管理此ID和真實認證人的關系。
var certifyId = JSON.parse(parms).extInfo.certifyId
function describe() {
// 攜帶CertifyId
fetch('http://獲取認證詳細數據接口地址', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: certifyId
})
.then(response => {
console.log('res', response)
return response.json()
})
.then(data => {
console.log('data', data)
document.getElementById('detail').innerHTML = JSON.stringify(data)
})
}
</script>
</body>
</html>
history路由不帶頁面錨點(#)
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Title</title>
</head>
<body>
<script>
// 此時的window.location.href就是ReturnUrl了。 不帶錨點格式為:https://aliyundoc.com/xxx
let url = new URL(window.location.href);
// 獲取返回的認證結果數據
let parms = url.searchParams.get('response')
console.log('parms:', parms)
// 如果需要二次驗證實人認證結果可參考下面代碼。
// 獲取CertifyId 為了避免盜鏈和篡改風險,請自行管理此ID和真實認證人的關系。
var certifyId = JSON.parse(parms).extInfo.certifyId
function describe() {
// 攜帶CertifyId
fetch('http://獲取認證詳細數據接口地址', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: certifyId
})
.then(response => {
console.log('res', response)
return response.json()
})
.then(data => {
console.log('data', data)
document.getElementById('detail').innerHTML = JSON.stringify(data)
})
}
</script>
</body>
</html>
history路由帶頁面錨點(#)
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Title</title>
</head>
<body>
<script>
// 此時的window.location.href就是ReturnUrl了。 帶錨點格式為:https://aliyundoc.com/xxx/#xxx
let url = new URL(window.location.href);
// 獲取返回的認證結果數據
let parms = JSON.parse(
decodeURIComponent(url.searchParams.get('response'))
);
console.log('parms:', parms)
// 如果需要二次驗證實人認證結果可參考下面代碼。
// 獲取CertifyId 為了避免盜鏈和篡改風險,請自行管理此ID和真實認證人的關系。
var certifyId = JSON.parse(parms).extInfo.certifyId
function describe() {
// 攜帶CertifyId
fetch('http://獲取認證詳細數據接口地址', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: certifyId
})
.then(response => {
console.log('res', response)
return response.json()
})
.then(data => {
console.log('data', data)
document.getElementById('detail').innerHTML = JSON.stringify(data)
})
}
</script>
</body>
</html>
hash路由
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Title</title>
</head>
<body>
<script>
// 此時的window.location.href就是ReturnUrl了。 hash格式為:https://aliyundoc.com/#/aaa/bbb
let url = new URL(window.location.href);
// 獲取返回的認證結果數據
let parms = JSON.parse(
decodeURIComponent(url.searchParams.get('response'))
);
console.log('parms:', parms)
// 如果需要二次驗證實人認證結果可參考下面代碼。
// 獲取CertifyId 為了避免盜鏈和篡改風險,請自行管理此ID和真實認證人的關系。
var certifyId = JSON.parse(parms).extInfo.certifyId
function describe() {
// 攜帶CertifyId
fetch('http://獲取認證詳細數據接口地址', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: certifyId
})
.then(response => {
console.log('res', response)
return response.json()
})
.then(data => {
console.log('data', data)
document.getElementById('detail').innerHTML = JSON.stringify(data)
})
}
</script>
</body>
</html>
ReturnUrl攜帶的錯誤碼說明
code說明
錯誤碼 | 是否計費 | 錯誤碼文案 | 錯誤碼描述 |
1000 | 是 | 刷臉成功 | 用戶完成了刷臉過程,認證建議結果為通過。該結果僅供參考,可通過調用服務端DescribeFaceVerify接口獲取最終認證結果。 |
1001 | 否 | 系統錯誤 | 表示系統錯誤。 |
1003 | 否 | 驗證中斷 | 表示驗證中斷。 |
2002 | 否 | 網絡錯誤 | 表示網絡錯誤。 |
2003 | 否 | 客戶端設備時間錯誤 | 表示客戶端設備時間錯誤。 |
2006 | 是 | 刷臉失敗 | 用戶完成了刷臉過程,認證建議結果為未通過。該結果僅供參考,可通過調用服務端DescribeFaceVerify接口獲取最終認證結果、未通過的詳細原因。 |
subCode說明
錯誤碼 | 描述 |
Z5050 | 人臉驗證成功。 |
Z5051 | 上傳刷臉圖片失敗。 |
Z5052 | 數據錯誤或程序異常。 |
Z5053 | 網絡錯誤。 |
Z5054 | 攝像頭無權限或無法獲取攝像頭數據。 |
Z5055 | 用戶退出。 |
Z5056 | 重試次數過多。 |
Z5057 | 視頻上傳超時。 |
Z5058 | 視頻格式不滿足要求。 |
Z5059 | 視頻中無有效人臉。 |
Z5128 | 驗證不是同一個人。 |