onfido ios sdk
32.1.0
SDK Onfido Smart Capture предоставляют набор экранов и функций, которые позволяют приложениям реализовывать потоки проверки личности пользователя. Каждый SDK содержит:
Все SDK Onfido Smart Capture организованы с использованием рабочих процессов Onfido Studio с незначительными различиями в настройке между доступными платформами.
Существуют две среды для поддержки интеграции Onfido SDK:
Используемая среда определяется токеном API, который используется для создания необходимого токена SDK.
Как только вы будете удовлетворены своей интеграцией и будете готовы к запуску, обратитесь в службу поддержки клиентов Onfido, чтобы получить активный токен API. Вам придется заменить токен песочницы в своем коде на живой токен.
Прежде чем начать работу, убедитесь, что вы ввели правильные платежные данные на панели управления Onfido.
iOS SDK поддерживает:
Примечание . Последней версией SDK для поддержки Xcode 11.5-12 является iOS SDK версии 22, Xcode 14+ — iOS SDK версии 29. При необходимости существует обходной путь для более старых версий Xcode. Пожалуйста, свяжитесь со службой поддержки клиентов Onfido для получения дополнительной информации.
Примечание . Для работы iOS SDK требуется CoreNFC (независимо от того, используете вы NFC или нет). Начиная с Xcode 12, существует ошибка, из-за которой в симуляторах отсутствует libnfshared.dylib . Для решения этой проблемы обратитесь к разделу «Переполнение стека».
Примечание . Если вы отключите функцию 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, и вы можете включить его в свой проект, добавив в свой подфайл следующее:
pod 'Onfido' Запустите pod install чтобы получить SDK.
SDK доступен на вкладке «Релизы» GitHub, где вы можете скачать сжатую платформу. Вы можете найти последний выпуск здесь.
Onfido.xcframeworkOnfido.xcframework в папку проекта.Onfido.xcframework расположенный в вашем проекте, в раздел « Embedded binaries на вкладке General целевого приложения iOS.Если ваше приложение не основано на Swift, вам необходимо создать новый файл Swift внутри вашего проекта. Этот файл необходим для того, чтобы Xcode упаковал библиотеки времени выполнения Swift, необходимые для запуска Onfido iOS SDK.
Создайте файл 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 , см. в определении конечной точки POST /workflow_runs/ в справочнике по API Onfido.
Обратите внимание , что в контексте SDK свойство
workflow_run_idназываетсяworkflowRunId.
При определении рабочих процессов и создании проверок личности мы настоятельно рекомендуем сохранить applicant_id для конкретного пользователя для возможного повторного использования. Это помогает отслеживать пользователей, если вы хотите выполнить несколько проверок личности одного и того же человека или в сценариях, когда пользователь возвращается и возобновляет процесс проверки.
SDK аутентифицируется с помощью токенов SDK. Onfido Studio генерирует и предоставляет токены SDK в полезных данных запуска рабочего процесса, возвращаемых API при создании запуска рабочего процесса.
Токены SDK для Studio можно использовать только вместе с конкретным запуском рабочего процесса, для которого они созданы, и остаются действительными в течение пяти недель.
Примечание . Никогда не используйте токены API во внешнем интерфейсе вашего приложения, поскольку злоумышленники могут обнаружить их в вашем исходном коде. Вы должны использовать их только на своем сервере.
Чтобы использовать SDK, вам необходимо получить экземпляр клиентского объекта, используя созданный вами токен SDK и идентификатор запуска рабочего процесса.
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Последние паспорта, национальные удостоверения личности и виды на жительство содержат чип, доступ к которому можно получить с помощью Near Field Communication (NFC). Onfido SDK предоставляет набор экранов и функций для извлечения этой информации, проверки ее подлинности и обеспечения итоговой проверки как части отчета о документе.
Начиная с версии 29.1.0 Onfido iOS SDK, NFC включен по умолчанию и предлагается конечным пользователям, если и документ, и устройство поддерживают NFC.
Дополнительную информацию о настройке NFC и списке поддерживаемых документов см. в руководстве NFC для отчетов о документах.
Для этой функции требуется возможность Near Field Communication Tag Reading в целевом приложении. Если вы еще не добавили его раньше, следуйте инструкциям в документации Apple.
Для поддержки документов NFC PACE вам необходимо отредактировать права приложения:
Near Field Communication Tag Reader Session FormatsPassword 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>
Чтобы настроить NFC с помощью Onfido Studio, вы можете использовать один из следующих вариантов в конструкторе рабочих процессов:
optional ): будет предпринята попытка чтения NFC, если это возможно. Чтобы настроить NFC в коде, вызовите функцию withNFC() при настройке OnfidoConfig (см. раздел «Расширенная настройка потока» ниже), используя указанные выше параметры.
️ Когда NFC настроен с помощью кода согласноrequired, в отличие от Studio, SDK не будет отфильтровывать типы документов, которые не поддерживают NFC. Для удобства конечного пользователя предоставляйте только типы документов, поддерживающие NFC, как указано здесь, или предпочтите использовать Studio.
iOS SDK поддерживает настройку цветов, шрифтов и строк, используемых в потоке SDK.
Чтобы настроить внешний вид SDK, вы можете передать необходимые значения CSS объекту Appearance в корне объекта WorkflowConfiguration .
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.
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} – необязательно
Самый эффективный способ добавить свой бренд в водяной знак нижнего колонтитула — использовать свойство cobrand в разделе enterpriseFeatures . Это свойство принимает 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 вы можете указать набор изображений, которые будут определены в свойстве logoCobrand в разделе enterpriseFeatures . Вы должны указать путь к изображению для использования в «темном» режиме и отдельному изображению для «светлого» режима. Оба изображения должны иметь разрешение 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 .
Вы можете назвать файл строк с переведенными ключами по своему усмотрению, но имя файла необходимо будет предоставить SDK в качестве параметра метода withCustomLocalization() :
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; (Цель-С)Дополнительно вы можете указать пакет, из которого следует читать файл строк:
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; (Цель-С)Примечание :
Чтобы запросить перевод на новый язык или оставить отзыв или предложения по предоставленным переводам, вы можете связаться со службой поддержки клиентов 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| АТРИБУТ | ПРИМЕЧАНИЯ |
|---|---|
| .успех | Обратный вызов, который срабатывает, когда все интерактивные задачи в рабочем процессе завершены. В случае успеха, если вы настроили веб-перехватчики, на ваш сервер будет отправлено уведомление, подтверждающее завершение рабочего процесса. Вам не нужно создавать проверку с помощью серверной части, поскольку она обрабатывается непосредственно рабочим процессом. |
| .error(Ошибка) | Обратный вызов, который срабатывает при возникновении ошибки |
| .отмена | Обратный вызов, который срабатывает, когда пользователь преждевременно завершает рабочий процесс. Причиной может быть .userExit или .consentDenied |
Объект Error , возвращаемый как часть OnfidoResponse.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 с использованием параметров, определенных в разделе «Расширенная настройка» этого документа, вы можете создавать проверки и получать результаты отчетов вручную с помощью API Onfido. Вы также можете настроить веб-перехватчики на асинхронное уведомление при создании результатов отчета.
В этом разделе «Расширенная настройка» описан процесс инициализации Onfido iOS SDK без использования Onfido Studio. Этот процесс требует ручного определения этапов проверки и их настройки.
Эти параметры шага потока являются взаимоисключающими с workflowRunId , что требует альтернативного метода создания экземпляра клиента и запуска потока.
Обратите внимание , что этот процесс инициализации не рекомендуется , поскольку большинство новых функций выпущены исключительно для рабочих процессов Studio.
SDK аутентифицируется с помощью токенов SDK. Поскольку каждый токен SDK должен быть специфичным для конкретного заявителя и сеанса, новый токен должен создаваться каждый раз при инициализации Onfido iOS SDK.
| Параметр | Примечания |
|---|---|
applicant_id | необходимый Указывает заявителя для экземпляра SDK. |
application_id | необходимый Идентификатор приложения (для iOS «идентификатор пакета приложений»), который был настроен во время разработки. Для iOS это обычно имеет вид com.your-company.app-name . Обязательно используйте действительный application_id , иначе вы получите ошибку 401. |
Подробную информацию о том, как вручную генерировать токены SDK, см. в определении POST /sdk_token/ в справочнике по API Onfido.
Примечание . Никогда не используйте токены API во внешнем интерфейсе вашего приложения, поскольку злоумышленники могут обнаружить их в вашем исходном коде. Вы должны использовать их только на своем сервере.
expireHandlerПри создании токенов SDK вручную важно отметить, что срок их действия истекает через 90 минут.
Учитывая это, мы рекомендуем использовать необязательный параметр expireHandler в функции настройки токена SDK для создания и передачи нового токена 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 и получив идентификатор заявителя, вы можете вручную настроить этапы потока 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 объекту Appearance в корне объекта OnfidoConfig.builder() .
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.
Вы можете настроить поток SDK, добавив шаги в поток SDK.
Возможные шаги включают в себя:
| Шаг | Описание |
|---|---|
withWelcomeStep | Экран приветствия, показанный пользователю с предварительными инструкциями. Варианты настройки включают изменение текстовых элементов и инструкций, отображаемых пользователю. |
withDocumentStep | Набор экранов, которые управляют захватом фотографии или загрузкой документа пользователя. Доступны многочисленные параметры настройки для определения списка документов, представляемого пользователю, и общего процесса захвата. |
withFaceStep | Набор экранов, управляющих съемкой селфи, видео или захватом движения пользователя. Параметры настройки позволяют выбрать вариант захвата. |
withProofOfAddressStep | Экран, на котором пользователь выбирает страну выдачи и тип документа для проверки своего адреса. |
Этот шаг представляет собой вводный экран SDK. Он знакомит с процессом и подготавливает пользователя к шагам, которые ему необходимо выполнить.
Хотя этот экран является необязательным , мы рекомендуем его удалить только в том случае, если у вас уже есть собственный экран приветствия для проверки личности.
Вы можете показать экран приветствия, вызвав configBuilder.withWelcomeStep() в Swift или [configBuilder withWelcomeStep] в Objective-C.
