刷臉認證提供iOS客戶端SDK,幫助您在業務應用(App)中實現刷臉認證功能。您可通過刷臉認證的服務端認證初始化接口,獲取刷臉認證唯一標識CertifyId,并使用CertifyId喚起刷臉認證客戶端SDK。本文將結合示例代碼進行iOS客戶端接入的詳細說明。
前提條件
系統版本:iOS 9.0 及以上
支持語言:Objective-C、Swift
SDK 不支持模擬器調試。
權限說明
iOS SDK權限說明如下:
權限 | 是否必選 | 使用目的 | 場景 |
NSCameraUsageDescription | 否 | 使用相機進行人臉識別。 | 實人認證方案、多因子意愿認證方案、活體人臉認證方案、活體檢測方案 |
NFCReaderUsageDescription | 否 | 使用NFC讀取證件信息。 | NFC認證方案 |
NSMicrophoneUsageDescription | 否 | 錄制音頻,用于意愿認證。 | 多因子意愿認證方案 |
REPLAYKIT | 否 | 錄屏功能,用于留存意愿認證過程視頻。 | 多因子意愿認證方案且開啟存證視頻功能 |
配置開發環境
在info.plist中配置攝像頭和麥克風權限請求(僅金融級多因子意愿認證方案需配置麥克風權限)。
在Xcode的編譯設置中關閉Enable Bitcode選項。
重要Xcode 15 開始 ENABLE_BITCODE 將不再生效,詳見:Xcode Release Notes。
在Xcode編譯設置的 中,添加設置-ObjC。
若您使用Xcode 15進行編譯,還需添加Id64。
如果您的工程設置了-force_load選項,則需要加入-force_load <framework path>/AliyunOSSiOS,命令之間以空格隔開,例如
-ObjC -force_load <framework path>/AliyunOSSiOS
。
配置依賴
下載iOS SDK。
該SDK為framework包。您需要在Xcode添加Link Binary With Libraries、SDK中的13個包和額外系統庫依賴。
解壓下載的SDK包,并在解壓的文件夾中執行以下命令提取所有的framework到Products目錄。
for i in $(ls *.tgz);do tar xvf $i;done
SDK中的包:
AliyunFaceAuthFacade.framework APBToygerFacade.framework APPSecuritySDK.framework BioAuthEngine.framework faceguard.framework DTFIdentityManager.framework DTFUtility.framework MultiFactorFacade.framework OCRDetectSDKForTech.framework ToygerNative.framework ToygerService.framework VerifyNativeAbility.framework
系統庫依賴:
CoreGraphics.framework Accelerate.framework SystemConfiguration.framework AssetsLibrary.framework CoreTelephony.framework QuartzCore.framework CoreFoundation.framework CoreLocation.framework ImageIO.framework CoreMedia.framework CoreMotion.framework AVFoundation.framework WebKit.framework libresolv.tbd libz.tbd libc++.tbd libc++.1.tbd libc++abi.tbd AudioToolbox.framework CFNetwork.framework MobileCoreServices.framework libz.1.2.8.tbd AdSupport.framework ReplayKit.framework
拷貝資源文件
選擇TARGETS,單擊Build Phases頁簽,在Copy Bundle Resources中添加以下bundle:
APBToygerFacade.bundle:位于APBToygerFacade.framework中。
ToygerService.bundle:位于ToygerService.framework中。
OCRXMedia.bundle:位于OCRDetectSDKForTech.framework中。
BioAuthEngine.bundle:位于BioAuthEngine.framework中。
MultiFactorFacade.bundle:位于MultiFactorFacade.framework中。
APBToygerFacadeSuitable.bundle:位于APBToygerFacade.framework中。
調用SDK
引入頭文件。
命令如下:
#import <AliyunFaceAuthFacade/AliyunFaceAuthFacade.h>
初始化SDK。
說明為了提升用戶體驗并為刷臉認證準備一些必備的數據,iOS客戶端需要初始化SDK。
您可以在
appDelegate
方法中調用初始化SDK的代碼(如下代碼塊所示),也可以在獲取metaInfo數據前調用初始化SDK代碼(如步驟3所示)。appDelegate
函數調用,示例代碼:- (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions { [AliyunFaceAuthFacade initSDK];// 初始化SDK。 }
IPv6網絡初始化,示例代碼如下:
- (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions { [AliyunFaceAuthFacade initIPv6];// 初始化SDK。 }
獲取metaInfo數據。
示例代碼如下:
[AliyunFaceAuthFacade initSDK]; // 初始化SDK,如果已經在appDelegate函數中調用過,此處無需再重復調用。 [AliyunFaceAuthFacade getMetaInfo];
IPv6網絡初始化,示例代碼如下:
[AliyunFaceAuthFacade initIPv6]; // 初始化SDK,如果已經在appDelegate函數中調用過,此處無需再重復調用。 [AliyunFaceAuthFacade getMetaInfo];
說明getMetaInfo 方法的返回值類型是NSDictionary,在調用服務端的發起認證請求接口時,您需要先將其轉為JSON格式。
關于發起認證請求的具體操作,請參見發起認證請求。
調用SDK開始認證。
示例代碼如下:
[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];
參數說明如下表所示。
名稱
類型
描述
certifyId
NSString
您可以通過服務端發起申請請求接口獲取該參數。關于發起認證請求的具體操作,請參見發起認證請求。
extParams
NSDictionary
通過以下代碼傳入當前ViewController,用于SDK展現網絡加載和認證頁面。
[extParams setValue:self forKey:@"currentCtr"];
重要請注意在 extParams 中務必傳入當前控制器,否則會導致 SDK 頁面無法正常展示。
如需設置OCR的下一步按鈕的顏色,在extParams中添加按鈕的正常顏色和按鈕按下時的顏色。代碼示例如下:
[extParams setValue:@"00FF00" forKey:ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_COLOR]; [extParams setValue:@"0000FF" forKey:ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_CLICKED_COLOR];
如需設置掃臉時的圓圈顏色,在extParams中添加圓圈顏色。代碼示例如下:
[extParams setValue:@"FF0000" forKey:ZIM_EXT_PARAMS_KEY_OCR_FACE_CIRCLE_COLOR];
金融級實人認證支持獲取活體檢測的視頻。如需獲取視頻,您可以在
extParams
中添加returnVideo
參數,并且將其值設置為true
(默認為false
),在使用金融級實人認證SDK完成認證(不區分認證結果為F或T)后將通過SDK回調返回本地視頻,也可以通過查詢接口獲取視頻。代碼示例如下:[extParams setValue:@"true" forKey:@"returnVideo"];
如需自定義X號(頁面關閉按鈕),您可以參照以下步驟:
如需自定義X號的圖片,需要額外在extParams中添加cancelImage,并設置值為UIImage。代碼示例如下:
[extParams setValue:UIImage forKey:@"cancelImage"];
如需自定義X號的圖片位置,需要額外在extParams中添加imageOrientation,并設置值為right或left 。默認為left。代碼示例如下:
[extParams setValue:@"right" forKey:@"imageOrientation"];
更多UI自定義設置,請參見iOS SDK UI自定義配置說明。
返回結果說明:
[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];
response.code
包含以下返回參數,具體說明如下表所示。錯誤碼
錯誤碼文案
錯誤碼描述
1000(ZIMResponseSuccess)
刷臉成功
用戶完成了刷臉過程,認證建議結果為通過。
該結果僅供參考,可通過調用服務端DescribeFaceVerify接口獲取最終認證結果。
1001(ZIMInternalError)
系統錯誤
表示系統錯誤。
1003(ZIMInterrupt)
驗證中斷
表示驗證中斷。
2002(ZIMNetworkfail)
網絡錯誤
表示網絡錯誤。
2003(ZIMTIMEError)
客戶端設備時間錯誤
表示客戶端設備時間錯誤。
2006(ZIMResponseFail)
刷臉失敗
用戶完成了刷臉過程,認證建議結果為未通過。
該結果僅供參考,可通過調用服務端DescribeFaceVerify接口獲取最終認證結果、未通過的詳細原因。
說明關于錯誤碼的更多信息,請參見金融級客戶端iOS錯誤碼詳情。
代碼示例:
[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) { dispatch_async(dispatch_get_main_queue(), ^{ NSString *title = @"刷臉成功"; switch (response.code) { case ZIMResponseSuccess://1000。 break; case ZIMInterrupt://1003。 title = @"用戶退出"; break; case ZIMNetworkfail://2002。 title = @"網絡錯誤"; break; case ZIMTIMEError: //2003。 title = @"設備時間設置不對"; break; case ZIMResponseFail: //2006。 title = @"刷臉失敗"; break; case ZIMInternalError://1001。 title = @"初始化失敗"; break; default: break; } }); }];
Demo代碼包
SDK包大小裁剪說明
更多說明,請參見SDK包裁剪說明。
SDK UI自定義設置
更多說明,請參見iOS SDK UI自定義配置說明。