> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/faceliveness.md). # Face Liveness (OBSOLETO) ## Versão atual | Nome | Versão | | -------------- | ------ | | `FaceLiveness` | 7.4.0 | ### Requisitos | Informações de implantação | Versão | | -------------------------- | ------ | | Alvo do iOS | 15.0+ | | Xcode | 16.2+ | | Swift | 5.5+ | * Um válido [Token móvel da Caf](https://github.com/combateafraude/public-docs/blob/docs-sdks/sdk_integration_documentation.md#2-generating-access-tokens). * CocoaPods instalados ### Dependências do SDK O FaceLiveness utiliza dois SDKs externos principais, gerenciados por meio do CocoaPods para uma integração simples: | SDK | Versão | | ---------------- | ------ | | `iProov` | 13.1.0 | | `FingerprintPro` | 2.7.0 | * [iProov Biometrics iOS](https://github.com/iProov/ios): Facilita a integração da tecnologia de verificação facial ao vivo. * [FingerprintPro iOS](https://github.com/fingerprintjs/fingerprintjs-pro-ios): Adiciona recursos de autenticação por impressão digital, aprimorando os recursos de segurança do seu app. ### Permissões em tempo de execução No `info.plist` arquivo, adicione as permissões abaixo: | Permissão | Motivo | Obrigatório | | ------------------------------------------ | ------------------------------------------------------------ | ----------- | | `Privacidade - Descrição de Uso da Câmera` | Captura da selfie em políticas de verificação facial ao vivo | Sim | ### Instalação #### CocoaPods No seu Podfile, especifique a referência ao nosso framework. Substituindo `` pela atual [versão](#current-version): ```ruby target 'your-project' do use_frameworks! pod 'FaceLiveness', '' ``` Para versões anteriores a `FaceLiveness 4.0.0`, você também deve incluir estas fontes adicionais no Podfile: ```ruby source 'https://github.com/combateafraude/iOS.git' source 'https://cdn.cocoapods.org/' ``` #### SPM 1. Abra seu projeto no Xcode. 2. Navegue até **Arquivo > Adicionar Pacotes**. 3. Na barra de pesquisa, cole a URL deste repositório: ```console https://github.com/combateafraude/FaceLiveness.git ``` ## Instanciando o SDK Primeiro, instancie um objeto do tipo `FaceLivenessSDK`. Este objeto é para você configurar todas as suas regras de negócio: ```swift class FaceLivenessViewController: UIViewController { var faceLiveness: FaceLivenessSDK? func setupFaceLiveness() { faceLiveness = FaceLivenessSDK.Build() // a tabela abaixo mostra todas as opções de configuração do SDK .build() faceLiveness?.delegate = self } func startFaceLiveness() { faceLiveness?.startSDK(viewController: self, mobileToken:"yourMobileToken", personId: "personId") } } ``` ### Opções do FaceLiveness | Parâmetro | Obrigatório | Valor Padrão | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------ | |

.startSDK(viewController: UIViewController, mobileToken: String, personId: String)

| | | |

.setStage(stage: CAFStage)

Usado para redirecionar o SDK para o ambiente desejado na API da caf. Ele possui as seguintes opções: .beta ou .prod.

| Não | `.prod` | |

.setFilter(filter: Filter)

Define o filtro da câmera aplicado à prévia da câmera. Ele possui as seguintes opções: .natural ou .lineDrawing

| Não | `.lineDrawing` | |

.setLoadingScreen(withLoading: Bool)

Este parâmetro booleano determina se a tela de carregamento será implementada por meio de um delegate ou se você usará a tela padrão. Se definido como 'true', a tela de carregamento será uma tela padrão do SDK. No caso de 'false', você deve usar a sessão 'LoadingScreen' e implementar os delegates.

| Não | **false** | |

.setImageUrlExpirationTime(time: Time)

Use para alterar o tempo padrão de expiração da URL da imagem para recuperar a captura da varredura. Ele possui as seguintes opções: .threeHours, .thirtyDays ou .thirtyMin.

| Não | **30 min** | |

.setAuthenticationBaseUrl(authBaseUrl: String)

Permite o uso de um proxy reverso para executar as autenticações do SDK. Define a URL base para autenticação; o protocolo deve ser HTTPS. Adiciona uma barra no final, se estiver ausente.

| Não | **URL padrão da Caf** | |

.setFaceLivenessBaseUrl(livenessBaseUrl: String)

Permite o uso de um proxy reverso para executar verificações de liveness facial. Define a URL base; o protocolo deve ser WSS. Adiciona uma barra no final, se estiver ausente. Requer certificados definidos por .setCertificates por segurança.

| Não | **URL padrão da iProov** | |

.setCertificates(certificates: \[String])

Define os protocolos codificados em Base64 do SHA256 para comunicação segura em implementações de proxy reverso. Obrigatório ao usar URLs personalizadas para autenticação ou verificações de liveness facial.

| Não | **Lista vazia** | |

.setCustomLocalization(named: String?)

Este método permite que você especifique um nome de recurso de localização personalizado para o módulo iProov. Quando um nome é fornecido, o SDK carregará o arquivo de localização correspondente em vez do pacote de recursos padrão. Para mais detalhes sobre o formato dos arquivos de localização e a integração, consulte a documentação de localização da iProov.

| Não | **nil** | ## Proxy reverso Para configurar as definições de proxy reverso, siga estas instruções: ### Proxy reverso do FaceLiveness * Configure seu proxy para se comunicar com a URL correspondente ao `CAFStage` que você está usando: * `CAFStage.PROD` -> `https://api.public.caf.io/v1/sdks/faces/` * `CAFStage.BETA` -> `https://api.public.beta.caf.io/v1/sdks/faces/` * `CAFStage.DEV` -> `https://api.public.dev.caf.io/v1/sdks/faces/` * Use o método `.setFaceLivenessBaseUrl` para definir a URL na qual o FaceLiveness deve ser executado. * **O protocolo da URL deve ser WSS.** * Use o `.setCertificates` método para definir os certificados, que devem ser o hash SHA-256 do Subject Public Key Info do certificado codificado em base64. * **Os certificados são necessários para que o proxy reverso do FaceLiveness funcione corretamente.** ```swift faceLiveness = FaceLivenessSDK.Build() .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/") .setCertificates(certificates: [ "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=", "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=", "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9=" ]) .build() ``` ### Proxy reverso de autenticação * Configure seu proxy para se comunicar com \`wss\://us.rp.secure.iproov.me/ws´. * Use o método `.setAuthenticationBaseUrl` para definir a URL na qual as solicitações de autorização devem ser executadas. * **O protocolo da URL deve ser HTTPS.** ```swift faceLiveness = FaceLivenessSDK.Build() .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/") .build(); ``` ## Obtendo os Resultados Você deve implementar a `FaceLivenessDelegate` classe para obter os resultados do SDK. Para isso, você deve fornecer um `UIViewController` à sua instância do SDK: ```swift faceLiveness?.delegate = self ``` ### Implementação do Delegate O delegate abaixo deve ser implementado para tratar os resultados do SDK.\ Ao implementar a extensão do delegate, você terá acesso a um objeto dependendo do tipo de retorno. Em cada caso, o objeto carrega informações diferentes. ```swift extension FaceLivenessViewController: FaceLivenessDelegate { func didFinishLiveness(with livenessResult: FaceLiveness.LivenessResult) { //tratar o resultado de sucesso } func didFinishWithError(with sdkError: FaceLiveness.SDKError) { //tratar o resultado de erro } func didFinishWithFailure(with sdkFailure: FaceLiveness.SDKFailure) { //tratar resultado de falha } func didFinishWithCancelled() { //tratar quando o usuário fecha o SDK } func onConnectionChanged(_ state: FaceLiveness.LivenessState) { //handle loading screen display } } ``` ### Tela de Carregamento Para criar uma tela de carregamento durante os processos de validação do SDK, você precisa implementar uma view com a tela de carregamento e exibir essa tela no `onConnectionChanged(_ state: FaceLiveness.LivenessState)` delegate function. | estado | descrição | tela de carregamento | | ---------- | ------------------------------------------------ | -------------------- | | fechado | O SDK foi fechado | fechar | | conectando | O SDK está se conectando ao servidor de liveness | exibir | | conectado | O SDK foi conectado ao servidor de liveness | fechar | Na implementação do SDK, é necessário adicionar a view à pilha de views usando o código a seguir. Isso torna a view visível. ```swift view.addSubview(loadingHUD) ``` Esta view deve ser adicionada antes do Builder de cada SDK. ## Resultados do SDK ### Casos de sucesso Ao final de uma execução bem-sucedida, você receberá um objeto do tipo `LivenessResult`. Esse objeto contém uma `signedResponse` propriedade contendo um token JWT com o resultado da execução. Esse token deve ser descriptografado para obter os detalhes dos resultados da execução. ```swift livenessResult.signedResponse ``` #### LivenessResult (Struct) | Propriedade | Descrição | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `signedResponse: String?` | Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação. | #### Parâmetros SignedResponse Dentro de `signedResponse`, o parâmetro `isAlive` define a execução do liveness, em que `true` é aprovado e `false` é rejeitado ([Caso de falha](#failure-cases) será retornado). | Evento | Descrição | | ------------ | -------------------------------------------------------------------------------- | | `requestId` | Identificador da solicitação. | | `isAlive` | Validação de uma pessoa viva, identifica se o usuário passou com sucesso ou não. | | `token` | Token da solicitação. | | `userId` | Identificador do usuário fornecido para a solicitação. | | `imageUrl` | Link temporário para a imagem, gerado pela nossa API. | | `personId` | Identificador do usuário fornecido para o SDK. | | `sdkVersion` | Versão do Sdk em uso. | | `iat` | Expiração do token. | {% hint style="warning" %} O **isAlive** parâmetro é **MUITO IMPORTANTE**, pois determina se o processo de validação prossegue ou é interrompido. Quando `isAlive: true`, o usuário recebe permissão para continuar sua jornada; por outro lado, se `isAlive: false`, o usuário é considerado inválido e o acesso a etapas posteriores da jornada deve ser negado. Esse parâmetro desempenha um papel fundamental na orientação do fluxo das operações. {% endhint %} ### Casos de erro Em caso de erros de execução, você receberá um objeto do tipo `SDKError`. Esse objeto engloba um enum contendo o `errorType`, e um `descrição`. #### SDKError (Struct) | Propriedade | Descrição | | ---------------------- | ----------------------- | | `errorType ErrorType?` | Retorna o tipo do erro. | | `description String?` | Descrição do erro. | #### ErrorType (Enum) | ErrorType | Descrição | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `dispositivoSemSuporte` | Indica que o hardware ou software do dispositivo não atende aos requisitos mínimos para reconhecimento facial. | | `permissãoDaCâmera` | Indica que o dispositivo não tem permissão para acessar a câmera, seja por negação do usuário ou por permissões ausentes no app. | | `exceçãoDeRede` | Indica um erro relacionado à rede, como ausência de conexão com a internet, timeouts do servidor ou congestionamento de rede. | | `exceçãoDeToken` | Indica um problema com o token de autenticação fornecido, como ser inválido, expirado ou não ter as permissões necessárias. | | `exceçãoDoServidor` | Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço. | | `exceçãoDeCertificado` | Indica que não há certificados válidos para a URL do proxy, impedindo a comunicação segura. | | `exceçãoDeCapturaJáAtiva` | Indica que uma captura de reconhecimento facial já está em andamento. Uma nova captura não pode ser iniciada até que a atual seja concluída. | | `exceçãoDeErroInesperado` | Indica que ocorreu um erro irrecuperável durante a transação de reconhecimento facial. | | `exceçãoDeTempoEsgotadoDoUsuário` | Indica um erro do lado do servidor, que pode incluir configurações incorretas do servidor, falhas de processamento ou interrupções no serviço. | | `exceçãoDeImagemNãoEncontrada` | Indica que um usuário demorou demais para concluir a solicitação. | | `exceçãoDeMuitasSolicitações` | Indica que o servidor recebeu mais solicitações do que está preparado para processar. | ### Casos de falha Em caso de falhas de execução, você receberá um objeto do tipo `SDKFailure`. Esse objeto engloba um enum contendo o `failureType`, `descrição` e um `signedResponse`. #### SDKFailure (Class) | Propriedade | Descrição | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `signedResponse String?` | Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação. | | `failureType String?` | Em caso de uma falha específica, retorne o tipo do erro. | | `failureMessage String?` | Em caso de uma falha específica, retorne as instruções para evitar o erro. | #### Tipos de falha Todos os motivos de falha são retornados exclusivamente nos fluxos de validação de liveness GPA. Nos fluxos de LA (Liveness Assurance), qualquer falha sempre retornará o erro genérico UNKNOWN, independentemente do problema específico encontrado. | FailureType | Descrição | LA | GPA | | -------------------- | ------------------------------------------------------ | -- | --- | | `unknown` | Tente novamente. | ✅ | ✅ | | `movimentoExcessivo` | Fique parado. | ❌ | ✅ | | `muitoBrilhante` | Vá para um lugar mais escuro. | ❌ | ✅ | | `muitoEscuro` | Vá para um lugar mais claro. | ❌ | ✅ | | `rostoDesalinhado` | Mantenha o rosto dentro do oval. | ❌ | ✅ | | `olhosFechados` | Mantenha os olhos abertos. | ❌ | ✅ | | `rostoMuitoLonge` | Aproxime o rosto da tela. | ❌ | ✅ | | `rostoMuitoPerto` | Afaste o rosto da tela. | ❌ | ✅ | | `sunglasses` | Remova os óculos de sol. | ❌ | ✅ | | `rostoObstruído` | Remova qualquer cobertura facial. | ❌ | ✅ | | `múltiplosRostos` | Certifique-se de que apenas uma pessoa esteja visível. | ❌ | ✅ | ### ⚠️ Configuração do Sandbox para iOS Se você encontrar o erro relacionado a `Sandbox: rsync.samba deny file-write-create` ao usar este SDK em um projeto iOS, siga as etapas abaixo: 1. No Xcode, vá para seu projeto na aba Build Settings. 2. No campo de busca, procure por sandbox. 3. Localize a opção User Script Sandboxing. 4. Altere o valor para No. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/ios/standalone-modules/faceliveness.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.