onfido ios sdk
32.1.0
Os SDKs Onfido Smart Capture fornecem um conjunto de telas e funcionalidades que permitem que os aplicativos implementem fluxos de verificação de identidade do usuário. Cada SDK contém:
Todos os SDKs do Onfido Smart Capture são orquestrados usando fluxos de trabalho do Onfido Studio, com apenas pequenas diferenças de personalização entre as plataformas disponíveis.
Existem dois ambientes para suportar as integrações do Onfido SDK:
O ambiente usado é determinado pelo token de API usado para gerar o token SDK necessário.
Quando estiver satisfeito com sua integração e pronto para entrar em operação, entre em contato com o Suporte ao Cliente da Onfido para obter um token de API ativo. Você terá que substituir o token sandbox em seu código pelo token ativo.
Verifique se você inseriu os detalhes de faturamento corretos em seu painel Onfido, antes de entrar no ar.
O SDK do iOS suporta:
Observação : a versão mais recente do SDK para suporte ao Xcode 11.5-12 é o iOS SDK versão 22, o Xcode 14+ é o iOS SDK versão 29. Há uma solução alternativa para versões mais antigas do Xcode, se necessário. Entre em contato com a equipe de Suporte ao Cliente da Onfido para obter mais informações.
Nota : O iOS SDK requer CoreNFC para ser executado (independentemente de você usar NFC ou não). Desde o Xcode 12, há um bug onde libnfshared.dylib está faltando nos simuladores. Consulte Stack Overflow para obter uma solução para esse problema.
Observação : caso você desative o recurso NFC, a Apple poderá solicitar que você forneça um vídeo para demonstrar o uso do NFC, pois o código relacionado ao NFC faz parte do binário do SDK, independentemente da configuração do tempo de execução. Enquanto estamos trabalhando em uma solução permanente para este problema, você pode entrar em contato com o Suporte ao Cliente da Onfido para obter um vídeo.
O SDK faz uso da câmera do dispositivo do usuário (para captura de documentos e rosto) e do microfone (para captura de vídeo e movimento). É necessário ter as seguintes chaves no arquivo Info.plist do seu aplicativo:
NSCameraUsageDescriptionNSMicrophoneUsageDescription< key >NSCameraUsageDescription</ key >
< string >Required for document and face capture</ string >
< key >NSMicrophoneUsageDescription</ key >
< string >Required for video capture</ string >Nota : Todas as chaves serão necessárias para o envio do aplicativo.
O SDK está disponível com o Swift Package Manager e você pode incluí-lo em seu projeto adicionando o seguinte URL do repositório de pacotes:
dependencies: [
. package ( url : " https://github.com/onfido/onfido-ios-sdk.git " , . branch ( " master " ) )
] O SDK também está disponível no CocoaPods e você pode incluí-lo em seu projeto adicionando o seguinte ao seu Podfile:
pod 'Onfido' Execute pod install para obter o SDK.
O SDK está disponível na guia GitHub Releases, onde você pode baixar a estrutura compactada. Você pode encontrar o lançamento mais recente aqui.
Onfido.xcframeworkOnfido.xcframework para a pasta do seu projetoOnfido.xcframework localizado em seu projeto à seção Embedded binaries na guia General do destino do seu aplicativo iOSSe o seu aplicativo não for baseado em Swift, você deverá criar um novo arquivo Swift dentro do seu projeto. Este arquivo é necessário para forçar o Xcode a empacotar as bibliotecas de tempo de execução Swift necessárias para a execução do Onfido iOS SDK.
Crie um arquivo Swift com o seguinte conteúdo:
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 " )
} Defina Always Embed Swift Standard Libraries como Yes na configuração do seu projeto.
️ A documentação de inicialização do SDK a seguir se aplica a fluxos de trabalho de verificação de identidade orquestrados usando o Onfido Studio. Para integrações em que as etapas de verificação são definidas e configuradas manualmente, consulte a seção Personalização avançada de fluxo abaixo.
O SDK do iOS possui diversas opções de inicialização e personalização que fornecem flexibilidade à sua integração, ao mesmo tempo em que permanecem fáceis de integrar.
Onfido Studio é a plataforma usada para criar fluxos de trabalho de verificação de identidade altamente reutilizáveis para uso com os SDKs Onfido. Para obter uma introdução ao trabalho com fluxos de trabalho, consulte nosso guia de primeiros passos ou o guia de produto Onfido Studio.
As sessões do SDK são orquestradas por um workflow_run_id específico da sessão, ele próprio derivado de um workflow_id , o identificador exclusivo de um determinado fluxo de trabalho.
Para obter detalhes sobre como gerar um workflow_run_id , consulte a definição de endpoint POST /workflow_runs/ na referência da API Onfido.
Observe que no contexto do SDK, a propriedade
workflow_run_idé chamada deworkflowRunId.
Ao definir fluxos de trabalho e criar verificações de identidade, é altamente recomendável salvar o applicant_id em um usuário específico para possível reutilização. Isso ajuda a acompanhar os usuários caso você queira executar várias verificações de identidade no mesmo indivíduo ou em cenários em que um usuário retorna e retoma um fluxo de verificação.
O SDK é autenticado usando tokens SDK. Onfido Studio gera e expõe tokens SDK na carga útil de execução de fluxo de trabalho retornada pela API quando uma execução de fluxo de trabalho é criada.
Os tokens SDK para Studio só podem ser usados junto com a execução de fluxo de trabalho específica para a qual foram gerados e permanecem válidos por um período de cinco semanas.
Observação : você nunca deve usar tokens de API no frontend do seu aplicativo, pois usuários mal-intencionados podem descobri-los em seu código-fonte. Você só deve usá-los em seu servidor.
Para usar o SDK, você precisa obter uma instância do objeto cliente, usando o token SDK gerado e o ID de execução do fluxo de trabalho.
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 resultPassaportes recentes, bilhetes de identidade nacionais e autorizações de residência contêm um chip que pode ser acessado usando Near Field Communication (NFC). Os Onfido SDKs disponibilizam um conjunto de ecrãs e funcionalidades para extrair esta informação, verificar a sua autenticidade e fornecer a verificação resultante como parte de um relatório de Documento.
A partir da versão 29.1.0 do Onfido iOS SDK, o NFC é habilitado por padrão e oferecido aos usuários finais quando o documento e o dispositivo suportam NFC.
Para obter mais informações sobre como configurar o NFC e a lista de documentos suportados, consulte o guia NFC para Relatório de Documentos.
Este recurso requer capacidade Near Field Communication Tag Reading no destino do seu aplicativo. Se você ainda não o adicionou, siga as etapas da documentação da Apple.
Para oferecer suporte a documentos NFC PACE, você precisa editar os direitos do aplicativo:
Near Field Communication Tag Reader Session FormatsPassword Authenticated Connection Establishment (PACE) na lista suspensa< key >com.apple.developer.nfc.readersession.formats</ key >
< array >
< string >PACE</ string >
< string >TAG</ string >
</ array > É necessário ter a seguinte chave no arquivo Info.plist do seu aplicativo:
< key >NFCReaderUsageDescription</ key >
< string >Required to read ePassports</ string >Info.plist do destino do seu aplicativo para poder ler as tags NFC corretamente. <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>
Para configurar NFC usando Onfido Studio, você pode usar uma das seguintes opções no construtor de fluxo de trabalho:
optional ): a leitura NFC será tentada, se possível Para configurar NFC no código, chame a função withNFC() enquanto configura OnfidoConfig (consulte a seção Personalização avançada de fluxo abaixo) usando as opções acima.
️ Quando o NFC é configurado conformerequiredcom o código, ao contrário do Studio, o SDK não filtrará os tipos de documentos que não são compatíveis com NFC. Para obter a melhor experiência do usuário final, exponha apenas os tipos de documentos compatíveis com NFC, conforme listado aqui, ou prefira usar o Studio
O iOS SDK oferece suporte à personalização de cores, fontes e strings usadas no fluxo do SDK.
Para personalizar a aparência do SDK, você pode passar os valores CSS necessários para o objeto Appearance , na raiz do objeto 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>;Consulte a documentação de personalização do SDK para obter detalhes sobre as opções de UI suportadas que podem ser definidas nesta propriedade.
O iOS SDK oferece suporte à personalização de tema escuro. Por padrão, o tema do dispositivo ativo do usuário será aplicado automaticamente ao Onfido SDK. No entanto, você pode cancelar a troca dinâmica de tema em tempo de execução e, em vez disso, definir um tema estaticamente no momento da construção, conforme mostrado abaixo. Neste caso, o fluxo sempre será exibido no tema selecionado independente do tema do dispositivo do usuário.
interfaceStyle permite forçar o modo claro ou escuro via .dark e .light respectivamente. Por padrão, está definido como .unspecified , que seguirá o estilo da interface do sistema.
Nota: O atributo anterior supportDarkMode agora está obsoleto. Por favor, use interfaceStyle .
Por exemplo, para definir o estilo da interface como .dark , você pode usar o código abaixo:
let appearance = Appearance ( )
appearance . setUserInterfaceStyle ( . dark ) ONAppearance *appearance = [ONAppearance new ];
[appearance setUserInterfaceStyle: UIUserInterfaceStyleDark];Para aplicar a aparência você pode usar os métodos abaixo:
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];O Onfido SDK permite duas opções de co-branding que afetam a exibição do logotipo Onfido na parte inferior das telas do Onfido.
cobrand {Object} - opcional
A maneira mais eficaz de adicionar sua marca à marca d’água do rodapé é usar a propriedade cobrand em enterpriseFeatures . Esta propriedade usa um parâmetro text .
let companyName = " MyCompany "
let enterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingText ( companyName )
. build ( ) NSString *companyName = @" MyCompany " ;
ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingText: companyName];
[enterpriseFeatures build ];Observação : a co-branding de texto deve ser habilitada pelo Onfido. Entre em contato com seu engenheiro de soluções ou gerente de sucesso do cliente para ativar o recurso.
logoCobrand {Object} - opcional
Como alternativa ao cobrand , você pode especificar um conjunto de imagens a serem definidas na propriedade logoCobrand em enterpriseFeatures . Você deve fornecer o caminho para uma imagem para uso no modo 'escuro' e uma imagem separada para o modo 'claro'. Ambas as imagens devem ter resolução de 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 ];Observação : a co-branding do logotipo deve ser habilitada pelo Onfido. Entre em contato com seu engenheiro de soluções ou gerente de sucesso do cliente para ativar o recurso.
Para aplicar co-branding, adicione o objeto de recursos empresariais ao OnfidoConfig :
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withEnterpriseFeatures ( enterpriseFeatures ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withEnterpriseFeatures: enterpriseFeatures];O Onfido SDK oferece suporte e mantém traduções para mais de 40 idiomas.
As strings usadas no SDK podem ser personalizadas com um Localizable.strings em seu aplicativo para o idioma desejado e configurando o fluxo usando o método withCustomLocalization() no construtor de configuração.
- ( void ) withCustomLocalization {
[ self . configBuilder withCustomLocalization ] ; // will look for localizable strings in your Localizable.strings file
}Para obter a lista de idiomas suportados pelo Onfido, consulte nossa documentação de personalização do SDK.
Observação : se nenhum idioma for selecionado, o SDK detectará e usará a configuração de idioma do dispositivo do usuário final. Se o idioma do dispositivo não for compatível, o SDK usará como padrão o inglês ( en_US ).
O SDK também pode ser exibido em um idioma personalizado para localidades que o Onfido não suporta atualmente. Você pode fornecer traduções completas ou parciais. Para qualquer chave sem tradução, o idioma padrão suportado será usado.
Ao adicionar traduções personalizadas, você deve adicionar todo o conjunto de chaves incluído no arquivo Localizable.strings .
Você pode nomear o arquivo de strings com as chaves traduzidas conforme desejar, mas o nome do arquivo deverá ser fornecido ao SDK como um parâmetro para o método withCustomLocalization() :
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; (Objetivo-C)Além disso, você pode especificar o pacote do qual será lido o arquivo de strings:
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; (Objetivo-C)Observação :
Para solicitar uma tradução de um novo idioma, ou oferecer feedback ou sugestões sobre as traduções fornecidas, você pode entrar em contato com o Suporte ao Cliente da Onfido
Quando a sessão do Onfido SDK termina, uma série de funções de retorno de chamada podem ser acionadas.
Para retornos de chamada avançados usados para análise de usuários e retorno de mídia enviada, consulte a seção Retornos de chamada avançados deste documento.
Para receber o resultado de um fluxo de trabalho concluído, você deve passar um retorno de chamada para a instância do OnfidoFlow . O código a seguir é fornecido como exemplo:
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| ATRIBUTO | NOTAS |
|---|---|
| .sucesso | Retorno de chamada que é acionado quando todas as tarefas interativas no fluxo de trabalho são concluídas. Em caso de sucesso, se você configurou webhooks, uma notificação será enviada ao seu back-end confirmando que a execução do fluxo de trabalho foi concluída. Você não precisa criar um cheque usando seu back-end, pois isso é tratado diretamente pelo fluxo de trabalho |
| .erro(Erro) | Retorno de chamada que é acionado quando ocorre um erro |
| .cancelar | Retorno de chamada que é acionado quando o fluxo de trabalho foi encerrado prematuramente pelo usuário. O motivo pode ser .userExit ou .consentDenied |
O objeto Error retornado como parte de OnfidoResponse.error(Error) é do tipo OnfidoFlowError . É um enum com vários casos dependendo do tipo de erro.
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
}
}Embora o SDK seja responsável por capturar e fazer upload da mídia e dos dados do usuário, os próprios relatórios de verificação de identidade são gerados com base em fluxos de trabalho criados usando o Onfido Studio.
Para obter um passo a passo sobre como criar uma verificação de identidade usando Onfido Studio e nossos SDKs, consulte nosso Guia de início rápido.
Se seu aplicativo inicializar o Onfido iOS SDK usando as opções definidas na seção Personalização avançada deste documento, você poderá criar verificações e recuperar resultados de relatórios manualmente usando a API Onfido. Você também pode configurar webhooks para serem notificados de forma assíncrona quando os resultados do relatório forem gerados.
Esta seção sobre 'Personalização avançada' refere-se ao processo de inicialização do Onfido iOS SDK sem o uso do Onfido Studio. Este processo requer uma definição manual das etapas de verificação e sua configuração.
Esses parâmetros de etapa de fluxo são mutuamente exclusivos com workflowRunId , exigindo um método alternativo para instanciar o cliente e iniciar o fluxo.
Observe que esse processo de inicialização não é recomendado , pois a maioria dos novos recursos são lançados exclusivamente para fluxos de trabalho do Studio.
O SDK é autenticado usando tokens SDK. Como cada token SDK deve ser específico para um determinado candidato e sessão, um novo token deve ser gerado cada vez que você inicializar o Onfido iOS SDK.
| Parâmetro | Notas |
|---|---|
applicant_id | obrigatório Especifica o solicitante da instância do SDK. |
application_id | obrigatório O ID do aplicativo (para iOS "ID do pacote de aplicativos") que foi configurado durante o desenvolvimento. Para iOS, geralmente está no formato com.your-company.app-name . Certifique-se de usar um application_id válido ou você receberá um erro 401. |
Para obter detalhes sobre como gerar tokens SDK manualmente, consulte a definição POST /sdk_token/ na referência da API Onfido.
Observação : você nunca deve usar tokens de API no frontend do seu aplicativo, pois usuários mal-intencionados podem descobri-los em seu código-fonte. Você só deve usá-los em seu servidor.
expireHandlerAo gerar tokens SDK manualmente, é importante observar que eles expiram após 90 minutos.
Com isso em mente, recomendamos que você use o parâmetro expireHandler opcional na função de configuração do token SDK para gerar e transmitir um novo token SDK quando ele expirar. Isso garante que o SDK continue seu fluxo mesmo depois que um token do SDK expirar.
Por exemplo:
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];
}];Depois de adicionar a dependência do SDK e ter um ID do candidato, você poderá configurar manualmente as etapas do fluxo do 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
} Para personalizar a aparência do SDK, você pode passar os valores CSS necessários para o objeto Appearance na raiz do objeto 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>;Para aplicar a aparência, você pode usar os métodos abaixo:
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];Consulte a documentação de personalização do SDK para obter detalhes sobre as opções de UI suportadas que podem ser definidas nesta propriedade.
Você pode personalizar o fluxo do SDK adicionando etapas ao fluxo do SDK.
As etapas possíveis incluem:
| Etapa | Descrição |
|---|---|
withWelcomeStep | Tela de boas-vindas mostrada ao usuário com instruções preliminares. As opções de personalização incluem modificação dos elementos de texto e instruções mostradas ao usuário. |
withDocumentStep | Conjunto de telas que controlam a captura via foto ou upload do documento do usuário. Inúmeras opções de personalização estão disponíveis para definir a lista de documentos apresentada ao usuário e a experiência geral de captura. |
withFaceStep | Conjunto de telas que controlam a captura de selfie, vídeo ou captura de movimento do usuário. As opções de personalização permitem a seleção da variante de captura. |
withProofOfAddressStep | Tela onde o usuário seleciona o país emissor e o tipo de documento para verificar seu endereço. |
Esta etapa é a tela de introdução do SDK. Ele apresenta o processo e prepara o usuário para as etapas que ele precisará concluir.
Embora esta tela seja opcional , recomendamos sua remoção apenas se você já tiver sua própria tela de boas-vindas de verificação de identidade.
Você pode mostrar a tela de boas-vindas chamando configBuilder.withWelcomeStep() em Swift ou [configBuilder withWelcomeStep] em Objective-C.
