onfido ios sdk
32.1.0
Onfido 智慧擷取 SDK 提供了一組螢幕和功能，使應用程式能夠實現使用者身份驗證流程。每個 SDK 包含：
所有 Onfido 智慧捕獲 SDK 均使用 Onfido Studio 工作流程進行編排，可用平台之間只有微小的客製化差異。
有兩種環境支援 Onfido SDK 整合：
所使用的環境由用於產生必要的 SDK 令牌的 API 令牌決定。
一旦您對整合感到滿意並準備好上線，請聯絡 Onfido 的客戶支援以取得即時 API 令牌。您必須將程式碼中的沙箱令牌替換為即時令牌。
在上線之前，請檢查您是否在 Onfido 控制面板中輸入了正確的帳單詳細資訊。
iOS SDK 支援：
注意：支援 Xcode 11.5-12 的最新 SDK 版本是 iOS SDK 版本 22，Xcode 14+ 是 iOS SDK 版本 29。請聯絡 Onfido 的客戶支援團隊以了解更多資訊。
注意：iOS SDK 需要 CoreNFC 才能運作（無論您是否使用 NFC）。從 Xcode 12 開始，存在一個錯誤，即模擬器中缺少libnfshared.dylib 。有關此問題的解決方案，請參閱 Stack Overflow。
注意：如果您停用 NFC 功能，Apple 可能會要求您提供影片來示範 NFC 的使用情況，因為無論執行時間配置如何，與 NFC 相關的程式碼都是 SDK 二進位檔案的一部分。當我們正在努力解決此問題時，您可以同時聯繫 Onfido 的客戶支援以獲取影片。
SDK 使用使用者裝置的攝影機（用於文件和臉部捕捉）和麥克風（用於視訊和動作捕捉）。您需要在應用程式的Info.plist檔案中包含以下鍵：
NSCameraUsageDescriptionNSMicrophoneUsageDescription< key >NSCameraUsageDescription</ key >
< string >Required for document and face capture</ string >
< key >NSMicrophoneUsageDescription</ key >
< string >Required for video capture</ string >注意：提交應用程式需要所有密鑰。
該 SDK 可透過 Swift Package Manager 取得，您可以透過新增以下套件儲存庫 URL 將其包含在您的專案中：
dependencies: [
. package ( url : " https://github.com/onfido/onfido-ios-sdk.git " , . branch ( " master " ) )
] 該 SDK 也可在 CocoaPods 上使用，您可以透過將以下內容新增至 Podfile 中將其包含在您的專案中：
pod 'Onfido'運行pod install獲取 SDK。
該 SDK 可在 GitHub Releases 標籤中找到，您可以在其中下載壓縮框架。您可以在此處找到最新版本。
Onfido.xcframework的壓縮 zip 文件Onfido.xcframework工件移至您的專案資料夾中Onfido.xcframework新增至 iOS 應用程式目標的General標籤中的Embedded binaries部分如果您的應用程式不是基於 Swift，那麼您必須在專案內建立新的 Swift 檔案。需要此檔案來強制 Xcode 打包 Onfido iOS SDK 運行所需的 Swift 運行時庫。
建立一個包含以下內容的 Swift 檔案：
import Foundation
import AVFoundation
import CoreImage
import UIKit
import Vision
func fixLibSwiftOnoneSupport ( ) {
// from https://stackoverflow.com/a/54511127/2982993
print ( " Fixes dyld: Library not loaded: @rpath/libswiftSwiftOnoneSupport.dylib " )
}在專案配置中將Always Embed Swift Standard Libraries設定為Yes 。
️ 以下 SDK 初始化文件適用於使用 Onfido Studio 編排的驗證工作流程。對於手動定義和配置驗證步驟的集成，請參閱下面的高級流程自訂部分。
iOS SDK 具有多個初始化和自訂選項，可為您的整合提供靈活性，同時保持易於整合。
Onfido Studio 是用於建立高度可重複使用的身份驗證工作流程以與 Onfido SDK 結合使用的平台。有關使用工作流程的介紹，請參閱我們的入門指南或 Onfido Studio 產品指南。
SDK 會話由特定於會話的workflow_run_id編排，該會話本身源自workflow_id （給定工作流程的唯一識別碼）。
有關如何產生workflow_run_id的詳細信息，請參閱Onfido API參考中的POST /workflow_runs/端點定義。
請注意，在 SDK 上下文中，
workflow_run_id屬性稱為workflowRunId。
在定義工作流程和建立身份驗證時，我們強烈建議針對特定使用者儲存applicant_id以供重複使用。如果您希望對同一個人執行多個身份驗證，或者在使用者返回並恢復驗證流程的情況下，這有助於追蹤使用者。
SDK 使用 SDK 令牌進行身份驗證。建立工作流程運行時，Onfido Studio 在 API 傳回的工作流程執行負載中產生並公開 SDK 令牌。
Studio 的 SDK 令牌只能與為其產生的特定工作流程運作一起使用，且有效期為五週。
注意：您絕不能在應用程式的前端使用 API 令牌，因為惡意使用者可能會在您的原始程式碼中發現它們。您應該只在您的伺服器上使用它們。
若要使用 SDK，您需要使用產生的 SDK 令牌和工作流程執行 ID 來取得客戶端物件的執行個體。
let workflowConfiguration = WorkflowConfiguration ( workflowRunId : " <WORKFLOW_RUN_ID> " , sdkToken : " <YOUR_SDK_TOKEN> " ) let onfidoRun = OnfidoFlow ( workflowConfiguration : orchestrationConfig )
customerViewController . present ( try onfidoRun . run ( ) , animated : true , completion : nil )
// listen for the result最近的護照、國民身分證和居留證都包含可使用近場通訊 (NFC) 存取的晶片。 Onfido SDK 提供了一組螢幕和功能來提取此資訊、驗證其真實性並提供驗證結果作為文件報告的一部分。
從 Onfido iOS SDK 版本 29.1.0 開始，NFC 預設為啟用，並且當文件和裝置都支援 NFC 時向最終用戶提供。
有關如何配置 NFC 和支援的文檔清單的更多信息，請參閱 NFC 文檔報告指南。
此功能需要您的應用程式目標具有Near Field Communication Tag Reading功能。如果您之前沒有新增過，請按照 Apple 文件中的步驟操作。
要支援 NFC PACE 文檔，您需要編輯應用程式權限：
Near Field Communication Tag Reader Session Formats鍵下的新條目Password Authenticated Connection Establishment (PACE)< key >com.apple.developer.nfc.readersession.formats</ key >
< array >
< string >PACE</ string >
< string >TAG</ string >
</ array >您需要在應用程式的Info.plist檔案中包含以下鍵：
< key >NFCReaderUsageDescription</ key >
< string >Required to read ePassports</ string >Info.plist檔案中，才能正確讀取 NFC 標籤。 <key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
<string>12FC</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
<string>D2760000850101</string>
</array>
若要使用 Onfido Studio 設定 NFC，您可以在工作流程建構器中使用下列選項之一：
optional ）：如果可能，將嘗試 NFC 讀取若要在程式碼中設定 NFC，請在使用上述選項設定OnfidoConfig時呼叫withNFC()函數（請參閱下方的進階流程自訂部分）。
️ 當使用程式碼根據required配置NFC 時，與Studio 不同，SDK 不會過濾掉不支援NFC 的文檔類型，為了最終用戶獲得最佳體驗，僅公開此處列出的支援NFC 的文檔類型，或者更喜歡使用Studio
iOS SDK 支援自訂 SDK 流程中使用的顏色、字體和字串。
若要自訂 SDK 的外觀，您可以將所需的 CSS 值傳遞給WorkflowConfiguration物件根中的Appearance物件。
let appearance = Appearance ( )
appearance . primaryColor = < DESIRED_UI_COLOR_HERE >
appearance . primaryTitleColor = < DESIRED_UI_COLOR_HERE > ONAppearance *appearance = [[ONAppearance alloc ] init ];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;請參閱 SDK 自訂文檔，以了解可在此屬性中設定的支援的 UI 選項的詳細資訊。
iOS SDK支援深色主題客製化。預設情況下，使用者的活動裝置主題將自動套用到 Onfido SDK。但是，您可以選擇在運行時退出動態主題切換，而是在建置時靜態設定主題，如下所示。在這種情況下，無論使用者的裝置主題為何，流程將始終以選定的主題顯示。
interfaceStyle允許您分別透過.dark和.light強制淺色或深色模式。預設情況下，它設定為.unspecified ，這將遵循系統的介面風格。
注意：以前的屬性supportDarkMode現已棄用。請改用interfaceStyle 。
例如，要將介面風格設為.dark ，可以使用以下程式碼：
let appearance = Appearance ( )
appearance . setUserInterfaceStyle ( . dark ) ONAppearance *appearance = [ONAppearance new ];
[appearance setUserInterfaceStyle: UIUserInterfaceStyleDark];要套用外觀，您可以使用以下方法：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];Onfido SDK 允許兩個聯名品牌選項，這些選項會影響 Onfido 螢幕底部 Onfido 標誌的顯示。
cobrand {Object} - 可選
將品牌加入頁腳浮水印的最有效方法是使用enterpriseFeatures下的cobrand屬性。此屬性採用text參數。
let companyName = " MyCompany "
let enterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingText ( companyName )
. build ( ) NSString *companyName = @" MyCompany " ;
ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingText: companyName];
[enterpriseFeatures build ];請注意：文字聯合品牌必須由 Onfido 啟用。請聯絡您的解決方案工程師或客戶成功經理以啟動該功能。
logoCobrand {Object} - 可選
作為cobrand的替代方案，您可以指定要在enterpriseFeatures下的logoCobrand屬性中定義的一組影像。您必須提供用於“暗”模式的影像的路徑和用於“亮”模式的單獨影像的路徑。兩個影像的解析度必須為 144x32。
let onfidoEnterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingLogo (
UIImage ( named : " imageName_for_lightmode " ) ! ,
cobrandingLogoDarkMode : UIImage ( named : " imageName_for_darkmode " ) !
)
. build ( ) ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingLogo:
[UIImage imageNamed: @" onfido-logo-white " ] cobrandingLogoDarkMode: [UIImage imageNamed: @" onfido-logo-grey " ]
];
[enterpriseFeatures build ];請注意：標誌聯合品牌必須由 Onfido 啟用。請聯絡您的解決方案工程師或客戶成功經理以啟動該功能。
若要套用聯合品牌，請將企業功能物件新增至OnfidoConfig ：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withEnterpriseFeatures ( enterpriseFeatures ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withEnterpriseFeatures: enterpriseFeatures];Onfido SDK 支援並維護 40 多種語言的翻譯。
SDK 中使用的字串可以透過在您的應用程式中為所需語言新增Localizable.strings並使用配置產生器上的withCustomLocalization()方法配置流程來自訂。
- ( void ) withCustomLocalization {
[ self . configBuilder withCustomLocalization ] ; // will look for localizable strings in your Localizable.strings file
}有關 Onfido 支援的語言列表，請參閱我們的 SDK 客製化文件。
注意：如果未選擇語言，SDK 將偵測並使用最終使用者的裝置語言設定。如果裝置的語言不受支持，SDK 將預設為英語 ( en_US )。
SDK 還可以針對 Onfido 目前不支援的區域設定以自訂語言顯示。您可以提供完整或部分翻譯。對於任何沒有翻譯的密鑰，將使用支援的預設語言。
新增自訂翻譯時，您必須新增Localizable.strings檔案中包含的整套鍵。
您可以根據需要使用翻譯後的金鑰命名字串文件，但必須將文件名稱作為withCustomLocalization()方法的參數提供給 SDK：
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; （目標-C）此外，您可以指定從中讀取字串檔案的套件：
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; （目標-C）筆記：
若要要求新的語言翻譯，或對所提供的翻譯提供回饋或建議，您可以聯絡 Onfido 的客戶支持
當 Onfido SDK 會話結束時，可能會觸發一系列回呼函數。
有關用於使用者分析和返回提交媒體的高級回調，請參閱本文檔的高級回調部分。
若要接收已完成工作流程的結果，您應該將回呼傳遞給OnfidoFlow執行個體。提供以下程式碼作為範例：
onfidoRun . with ( responseHandler : { ( response : OnfidoResponse ) in
switch response {
case . success :
// User completed the flow
case . cancel ( let cancellationReason ) :
// Flow cancelled by user
print ( cancellationReason )
case . error ( let error ) :
// Error occurred
print ( error )
}
} ,
dismissFlowOnCompletion : true )
// Dismiss the whole flow when the user completes it, and return back to the integrator view| 屬性 | 筆記 |
|---|---|
| 。 | 當工作流程中的所有互動式任務完成時觸發的回調。成功後，如果您設定了 Webhook，系統將會向您的後端發送通知，確認工作流程運作已完成。您不需要使用後端建立支票，因為這是由工作流程直接處理的 |
| .錯誤（錯誤） | 發生錯誤時觸發的回調 |
| 。 | 當使用者提前退出工作流程時觸發的回調。原因可以是.userExit或.consentDenied |
作為OnfidoResponse.error(Error)的一部分傳回的Error物件的類型為OnfidoFlowError 。它是一個具有多種情況的枚舉，具體取決於錯誤類型。
switch response {
case let OnfidoResponse . error ( error ) :
switch error {
case OnfidoFlowError . cameraPermission :
// This happens if the user denies permission to the SDK during the flow
case OnfidoFlowError . failedToWriteToDisk :
// This happens when the SDK tries to save capture to disk, maybe due to a lack of space
case OnfidoFlowError . microphonePermission :
// This happens when the user denies permission for microphone usage by the app during the flow
case OnfidoFlowError . upload ( let OnfidoApiError ) :
// This happens when the SDK receives an error from an API call.
// See https://documentation.onfido.com/api/latest#errors for more information
case OnfidoFlowError . exception ( withError : let error , withMessage : let message ) :
// This happens when an unexpected error occurs.
// Please email [Customer support](mailto:supportonfido.com) when this happens
case OnfidoFlowError . versionInsufficient :
// This happens when you are using an older version of the iOS SDK and trying
// to access a new functionality from workflow. You can fix this by updating the SDK
default : // necessary because of Swift
}
}雖然 SDK 負責擷取和上傳使用者的媒體和數據，但身分驗證報告本身是根據使用 Onfido Studio 建立的工作流程產生的。
有關使用 Onfido Studio 和我們的 SDK 建立驗證的逐步演練，請參閱我們的快速入門指南。
如果您的應用程式使用本文檔進階自訂部分中定義的選項初始化 Onfido iOS SDK，您可以使用 Onfido API 手動建立檢查並擷取報告結果。您也可以將 Webhooks 設定為在產生報告結果時非同步收到通知。
本節「進階客製化」是指在不使用 Onfido Studio 的情況下初始化 Onfido iOS SDK 的過程。此過程需要手動定義驗證步驟及其配置。
這些流程步驟參數與workflowRunId互斥，需要另一種方法來實例化客戶端並啟動流程。
請注意，不建議執行此初始化過程，因為大多數新功能都是專門針對 Studio 工作流程發布的。
SDK 使用 SDK 令牌進行身份驗證。由於每個 SDK 令牌必須特定於給定的申請人和會話，因此每次初始化 Onfido iOS SDK 時都必須產生新令牌。
| 範圍 | 筆記 |
|---|---|
applicant_id | 必需的 SDK實例的申請者。 |
application_id | 必需的 在開發過程中設定的應用程式 ID（對於 iOS「應用程式套件 ID」）。對於 iOS，這通常採用 com.your-company.app-name形式。請確保使用有效的application_id ，否則您將收到 401 錯誤。 |
有關如何手動產生 SDK 令牌的詳細信息，請參閱 Onfido API 參考中的POST /sdk_token/定義。
注意：您絕不能在應用程式的前端使用 API 令牌，因為惡意使用者可能會在您的原始程式碼中發現它們。您應該只在您的伺服器上使用它們。
expireHandler管理SDK令牌過期手動產生 SDK 令牌時，請務必注意它們會在 90 分鐘後過期。
考慮到這一點，我們建議您在 SDK 令牌配置函數中使用可選的expireHandler參數來產生並在過期時傳遞新的 SDK 令牌。這確保了即使在 SDK 令牌過期後，SDK 仍能繼續其流程。
例如：
func getSDKToken ( _ completion : @escaping ( String ) -> Void ) {
// Your network request logic to retrieve SDK token goes here
completion ( myNewSDKtoken )
}
let config = try OnfidoConfig . builder ( )
. withSDKToken ( " <YOUR_SDK_TOKEN> " , expireHandler : getSDKToken ) -( void ) getSDKToken: ( void (^)( NSString *)) handler {
// <Your network request logic to retrieve SDK token goes here>
handler (sdkToken);
}
ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withSdkToken: @" YOUR_SDK_TOKEN " expireHandler: ^( void (^ handler)( NSString * expireHandler)) {
[ self getSDKToken: handler];
}];新增 SDK 依賴項並擁有申請人 ID 後，您可以手動設定 SDK 流程步驟：
let config = try OnfidoConfig . builder ( )
. withSDKToken ( " <YOUR_SDK_TOKEN> " )
. withWelcomeStep ( )
. withDocumentStep ( )
. withProofOfAddressStep ( )
. withFaceStep ( ofVariant : . photo ( withConfiguration : nil ) )
. build ( )
let onfidoFlow = OnfidoFlow ( withConfiguration : config )
. with ( responseHandler : { results in
// Callback when flow ends
} ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withSdkToken: @" YOUR_SDK_TOKEN " ];
[configBuilder withWelcomeStep ];
[configBuilder withDocumentStep ];
[configBuilder withProofOfAddressStep ];
NSError *variantConfigError = NULL ;
Builder *variantBuilder = [ONFaceStepVariantConfig builder ];
[variantBuilder withPhotoCaptureWithConfig: NULL ];
[configBuilder withFaceStepOfVariant: [variantBuilder buildAndReturnError: &variantConfigError]];
if (variantConfigError == NULL ) {
NSError *configError = NULL ;
ONFlowConfig *config = [configBuilder buildAndReturnError: &configError];
if (configError == NULL ) {
ONFlow *onFlow = [[ONFlow alloc ] initWithFlowConfiguration: config];
[onFlow withResponseHandler: ^(ONFlowResponse *response) {
// Callback when flow ends
}];
}
} try onfidoRun . run ( from : yourViewController , animated : true ) NSError *runError = NULL ;
[onFlow runFrom: yourViewController animated: YES error: &runError completion: nil ];
if (runError != NULL ) {
// do fallback logic
}若要自訂 SDK 的外觀，您可以將所需的 CSS 值傳遞給OnfidoConfig.builder()物件根目錄中的Appearance物件。
let appearance = Appearance ( )
appearance . primaryColor = < DESIRED_UI_COLOR_HERE >
appearance . primaryTitleColor = < DESIRED_UI_COLOR_HERE > ONAppearance *appearance = [[ONAppearance alloc ] init ];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;要套用外觀，您可以使用以下方法：
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];請參閱 SDK 自訂文檔，以了解可在此屬性中設定的支援的 UI 選項的詳細資訊。
您可以透過為 SDK 流程新增步驟來自訂 SDK 的流程。
可能的步驟包括：
| 步 | 描述 |
|---|---|
withWelcomeStep | 向使用者顯示帶有初步說明的歡迎畫面。自訂選項包括對向使用者顯示的文字元素和說明的修改。 |
withDocumentStep | 一組螢幕，用於控制透過照片擷取或上傳使用者文件。許多自訂選項可用於定義呈現給使用者的文件清單和整體擷取體驗。 |
withFaceStep | 控制使用者自拍照、影片或動作捕捉的一組螢幕。自訂選項允許選擇捕獲變體。 |
withProofOfAddressStep | 使用者選擇簽發國家和文件類型以驗證其地址的畫面。 |
這一步是SDK的介紹介面。它介紹了該過程並讓用戶為他們需要完成的步驟做好準備。
雖然此畫面是可選的，但我們僅建議您在已有自己的身份驗證歡迎畫面的情況下將其刪除。
您可以透過呼叫 Swift 中的configBuilder.withWelcomeStep()或 Objective-C 中的[configBuilder withWelcomeStep]來顯示歡迎畫面。
