欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32

是

-

業務ID，業務的唯一標識，用於追蹤業務。例如，商戶業務相關資料庫中的序號。

說明：ZOLOZ伺服器不檢查該欄位的值是否唯一。為了更便捷地追蹤業務，建議開啟商戶伺服器，並確保業務ID的唯一性。

"2017839040588699"

metaInfo

String

512

是

-

SDK和使用者裝置的元資訊。該欄位的值由ZOLOZ SDK以JSON字串格式返回。

說明：不要修改傳回值，直接傳遞即可。如果是H5接入模式，則設定為MOB_H5。

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

64

是

-

商戶的使用者ID或其他可用於識別某一使用者的標識，例如手機號碼、電子郵件地址等。

建議對userId欄位的值進行預脫敏，例如進行雜湊處理。

"not mandatory"

serviceLevel

String

32

否

FACECAPTURE0002

人臉活體檢測和使用者動作檢測的服務等級。取值如下：

• FACECAPTURE0001：ZOLOZ使用無互動人臉活體檢測。

• FACECAPTURE0002：ZOLOZ使用眨眼檢測方法進行活體檢測。

• FACECAPTURE0003：ZOLOZ使用多動作檢測方法進行活體檢測。這些動作從以下列表中隨機播放兩個：眨眼、張嘴、抬頭、低頭、左搖頭、右搖頭。

• FACECAPTURE0005：ZOLOZ使用眨眼檢測方法進行活體檢測。該服務等級會額外採集一張閉眼的人臉圖片，且該服務等級僅支援在原生SDK模式下使用。

• FACECAPTURE0010：ZOLOZ使用眨眼檢測方法進行活體檢測。該服務等級會額外採集一張閉眼的人臉圖片，且該服務等級僅支援在Web SDK模式下使用。

"FACECAPTURE0002"

operationMode

String

32

否

STANDARD

為身分識別驗證配置操作模式。取值如下：

• CLOSED：所有的演算法和風控規則都未開啟。該操作模式可用於測試情境，測試進程不受演算法和風控規則的影響。

• STANDARD：推薦的標準模式。

• LOOSE：相對寬鬆的模式，可用於低風險情境。

• STRICT：相對嚴格的模式，可用於高風險情境。

"STANDARD"

h5ModeConfig

H5ModeConfig

-

否

null

H5 Face Capture的配置資訊。詳細資料，請參見H5ModeConfig。

{ "completeCallbackUrl":"http://xxx/result.html", "interruptCallbackUrl":"http://xxx/result.html" }

productConfig

ProductConfig

-

否

null

為Face Capture產品提供更精細化的控制。詳細資料，請參見ProductConfig。

說明：如果同時設定了productConfig、serviceLevel和operationMode，則serviceLevel和operationMode均不生效，ZOLOZ將唯讀取productConfig的值。

{ "livenessMode":"STANDARD", "antiInjectionMode":"CLOSED", "actionCheckItems":["FACEBLINK","HEADLOWER"], "actionRandom":"Y", "actionFrame:":["EYECLOSE"] }

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

state

String

128

否

transactionId欄位的值

用於恢複客戶內容相關的標識符。

您可以為該欄位設定任何值，當ZOLOZ SDK回調商戶的移動App時將該值作為參數進行傳遞。

"G006600016CN20190114000000009572520355"

completeCallbackUrl

String

128

是

-

當整個身分識別驗證完成時，為瀏覽器指定即將重新導向的回調URL。

"http://xxx/result.html"

interruptCallbackUrl

String

128

是

-

當進程中斷時，為瀏覽器指定重新導向到的回調URL。

"http://xxx/result.html"

isIframe

String

1

否

N

是否需要在iframe中開啟網頁，如果需要設定為Y，否則設定為N。

"Y"

locale

String

16

否

en

網頁語言，目前僅支援以下語言：

• en（英語）

• id（印尼語）

• fl（菲律賓語）

"en"

uiCfg

String

256

否

null

自訂UI配置，採用JSON字串格式。僅支援isDesktop。

"{\"isDesktop\":\"Y\"}"

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

livenessMode

String

10

否

STANDARD

人臉活體檢測等級。取值如下：

• CLOSED：所有的演算法和風控規則都未開啟。該等級可用於測試情境，測試進程不受演算法和風控規則的影響。

• STANDARD：推薦的標準等級。

• LOOSE：相對寬鬆的等級，可用於低風險情境。

• STRICT：相對嚴格的等級，可用於高風險情境。

"STANDARD"

antiInjectionMode

String

10

否

CLOSED

該參數已廢棄，後續不再維護，為了保證API相容性，該參數會繼續保留。

防注入檢測等級。防注入檢測能夠有效抵禦使用換臉圖片或視頻進行的注入攻擊。取值如下：

• CLOSED：所有的防注入演算法都不開啟。如果業務情境不需要注入攻擊檢測，則不需要開啟。

• STANDARD：推薦的標準等級。

• LOOSE：預留等級，暫不支援使用。

• STRICT：預留等級，暫不支援使用。

注意：開啟防注入檢測會略微增加誤判率和已耗用時間，開啟前請先聯絡ZOLOZ支援人員。

"CLOSED"

deeperMode

String

10

否

CLOSED

AIGC攻擊檢測的Deeper等級，Deeper檢測功能的詳細介紹，請參見什麼是Deeper。該參數支援以下取值：

• CLOSED：Deeper的所有能力均不開啟，例如AIGC檢測演算法、終端風險檢測等。如果業務情境不需要AIGC攻擊檢測，則無需開啟。

• STANDARD：推薦的標準等級。

• LOOSE：相對寬鬆的等級，可用於低風險情境。

• STRICT：相對嚴格的等級，可用於高風險情境。

注意：需要先購買Deeper產品，才能使用該功能。

"CLOSED"

actionCheckItems

List<String>

-

否

FACEBLINK

用戶端和Web端的動作檢測列表。取值如下：

• FACEBLINK：眨眼

• MOUTHOPEN：張嘴

• HEADSHAKE：搖頭

• HEADLOWER：低頭

• HEADRAISE：抬頭

說明：為了更好的使用者體驗，不建議使用兩種及以上的動作。

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

否

N

用戶端和Web端的動作檢測順序是否隨機。取值如下：

• Y：隨機。

• N：不隨機，則按照actionCheckItems中的順序進行檢測。

"Y"

actionFrame

List<String>

-

否

null

採集其他幀圖片。取值如下：

• EYECLOSE：設定此值可返回在眨眼檢測過程中採集的閉眼幀。

["EYECLOSE"]

rearCamera

String

1

否

N

是否使用後置網路攝影機，僅支援在Web SDK模式下使用。取值如下：

• Y：使用後置網路攝影機。

• N：使用自拍。

說明：當rearCamera設定為Y時，使用後置網路攝影機採集人臉，僅支援靜默採集或眨眼採集。

"Y"

cropFaceImage

String

1

否

N

是否額外返回一張裁剪出臉部地區的人臉圖片。取值如下：

• Y：是

• N：否

"Y"

checkDeviceRisk

String

1

否

N

是否開啟裝置風險檢測。取值如下：

• Y：開啟裝置風險檢測。

• N：不開啟裝置風險檢測。

"Y"

欄位名稱

資料類型

必須返回

描述

樣本值

result

Result

是

API請求結果，包含結果狀態、結果碼和結果訊息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

ZOLOZ伺服器為人臉採集進程產生的唯一事務ID。此ID將作為Face Capture checkresult API請求的輸入參數。

說明：僅當交易進入處理階段後系統才會返回transactionId。如果在開始處理交易之前發生錯誤，系統不會返回transactionId。包括但不限於以下情況：

• 請求參數非法，例如入參格式錯誤或缺失必傳參數。

• 請求未能成功到達伺服器，例如網路問題或網關故障。

• 系統限流導致請求被拒絕。

"G006600016CN20190114000000009572520355"

clientCfg

String

否

用戶端配置資訊，包括SDK串連和行為參數。

說明：當result.resultStatus的值為S時，才返回該欄位。

"……"

結果碼

結果狀態

描述

SUCCESS

S

API調用成功。

HIGH_RISK

F

檢測到高風險。使用者帳號被風險引擎凍結。

DEVICE_NOT_SUPPORT

F

不支援當前的裝置類型。

OS_NOT_SUPPORT

F

不支援當前裝置的作業系統。

SDKVERSION_NOT_SUPPORT

F

不支援ZOLOZ SDK當前的版本。

INVALID_ARGUMENT

F

輸入參數無效。關於無效參數的詳細資料，請查看返回的resultMessage。

SYSTEM_ERROR

F

其他內部錯誤。有關錯誤詳情，請查看返回的resultMessage。