SDK IOS Liveness

v.2.0.4

🚧

A partir do dia 16 de abril de 2024, na versão 2.0.0, foi alterado o layout padrão do SDK e implementada a feature de customização de cores. Para entender como customiza-la em sua aplicação, leia mais aqui.

Introdução

O objetivo deste manual é fornecer todas as informações necessárias para instalação e uso da ferramenta nos aplicativos desenvolvidos para plataforma iOS.

Este SDK realiza a captura de faces para processamento de Liveness pela ClearSale. Todas as informações coletadas são dados relacionados apenas ao dispositivo, sem relação com aplicativo integrado.

As informações de captura de imagem dependem da permissão concedida pelo usuário no momento de captura. Neste caso é necessário que o aplicativo solicite o acesso à câmera ao usuário para dar prosseguimento com a coleta de prova de vida.

O SDK respeita a política de privacidade da Apple para a captura dos dados do dispositivo e o nível de permissão atribuído pelo usuário (usuário do dispositivo).

iOS

Requisitos

  • Versão do sistema operacional iOS: 12.0 ou superior.
  • Versão do projeto Swift 4+: funciona com Xcode superior ao 13.
  • Espaço de armazenamento: ~39mb

Instalação do Pacote

  • CocoaPods

Para adicionar o SDK ao seu projeto utilizando Cocoapods basta adicionar o seguinte comando ao seu Podfile:

Instalação em ambiente de homologação

platform :ios, '12.0'

use_frameworks!

target 'NOME_DO_SEU_PROJETO' do
pod 'CSLivenessSDK', :git => 'URL DO REPOSITÓRIO ENVIADO PELA CLEARSALE', :tag => 'VERSION-hml'
end

Instalação em ambiente de produção

platform :ios, '12.0'

use_frameworks!

target 'NOME_DO_SEU_PROJETO' do
pod 'CSLivenessSDK', :git => 'URL DO REPOSITÓRIO ENVIADO PELA CLEARSALE', :tag => 'VERSION'
end

Obs: O PAT do iOS é enviado junto da URL do Repositório pela ClearSale.

Configuração

Instruções para configuração do framework no projeto:

  1. Adicionar as seguintes entradas ao arquivo Info.plist do projeto de destino:
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera.</string>

Classe CSLiveness

Descrição
CSLiveness é a classe responsável pela inicialização do SDK.

Construtores
Esta classe possui um construtor público que deverá receber informações de autenticação e um booleano para ativar ou desativar o Vocal Guidance:

ParâmetrosDescrição
configuration: CSLivenessConfigObjeto com as configurações que serão utilizadas pela instância do CSLiveness.
vocalGuidance: boolBooleano para habilitar ou desabilitar áudios com falas humanas para guiar o usuário no processo de Liveness.

Classe CSLivenessConfig

Descrição
CSLivenessConfig responsável pela configuração para que o SDK consiga realizar suas tarefas.

Construtores
Esta classe possui um construtor público que deverá receber informações de autenticação:

ParâmetrosDescrição
clientId: StringIdentifica o cliente junto com a ClearSale (valor fornecido pela ClearSale).
clientSecret: StringToken que funciona como autenticação para identificação do cliente a utilizar o serviço (valor fornecido pela ClearSale).
identifierId: StringString de até 100 caracteres que identifica todo o fluxo do usuário de forma única e é gerada pela entidade. Serve para agilizar consultas e chamados feitos pela entidade (e pode ser utilizada como identificador interno entre produtos aqui da ClearSale).
cpf: StringString de 11 caracteres (no formato CPF) do usuário que irá realizar o fluxo, devendo seguir as regras de validade estipuladas pelo Governo.
colors: CSLivenessColorsConfigClasse responsável por receber os parâmetros de customização de cores do SDK. Para mais informações, visite a sessão de [customização de UI].

Classe CSLivenessColorsConfig

Descrição
CSLivenessColorsConfig é a classe responsável por receber os parâmetros de customização de cores do SDK:

ParâmetroDescrição
primaryColor: UIColorCor definida para atuar como PrimaryColor
secondaryColor: UIColorCor definida para atuar como SecondaryColor
titleColor: UIColorCor definida para atuar como TitleColor
paragraphColor: UIColorCor definida para atuar como ParagraphColor

Para mais informações, visite a sessão de customização de UI

Enum CSLivenessError

Descrição
Representa os erros que serão lançados pelo CSLivenessDelegate.

Cases
Este enum possui os seguintes cases:

Nome do caseDescrição
alreadyOpenedO SDK já está aberto e foi feita uma nova chamada para abri-lo novamente.
authenticationFalha na autenticação com os dados atribuídos no ClearsaleLivenessConfigurations.
backgroundIndica que o app que contém o sdk passou a ser executado em background e por isso o sdk foi finalizado.
cameraInitializationIssueFalha ao inicializar câmera.
cameraPermissionDeniedO Usuário não permitiu acesso à câmera.
landscapeModeNotAllowedIndica que o usuário rotacionou celular para landscape.
lowMemoryIndica pouco recurso de memória no aparelho do usuário para processamento do Liveness.
maxRetryMáximo de tentativas para tentar realizar a prova de vida.
networkErro de conexão de rede.
timeoutO Usuário não interagiu com o Liveness.
unexpectedIndica que ocorreu um erro inesperado na execução do SDK.
userCancelUsuário cancelou a ação de Liveness.
invalidIdentifierIdIdentifier Id inválido.
invalidCPFCpf inválido.
noneAconteceu um erro na hora de enviar a resposta.

Class CSLivenessResult

Descrição
Representa os resultados que serão lançados pelo CSLivenessDelegate.

Propriedades
Esta classe possui as seguintes propriedades:

PropriedadeDescrição
real: boolIndica que a prova de vida foi concluída e se é uma pessoa real ou não.
sessionId: StringEsse id identifica a captura do Liveness dentro da ClearSale e poderá ser usado para a consulta da imagem.
image: StringÉ um base64 da imagem autenticada pelo processo de Liveness.

Exemplos

Chamada na ViewController.


    private var livenessSdk: CSLiveness?
    ...

		let colors = CSLivenessColorsConfig(
    	primaryColor: UIColor,
      secondaryColor: UIColor,
      titleColor: UIColor,
      paragraphColor: UIColor
    )

		let configuration = CSLivenessConfig(
       clientId: String.clientId,
       clientSecret: String.clientSecret,
       identifierId: String.identifierId,
       cpf: String.cpf,
       colors: colors
     )

    self.livenessSdk = CSLiveness(configuration: configuration), vocalGuidance: bool)
    self.livenessSdk?.delegate = self
    self.livenessSdk?.start(viewController: self, animated: true);

Implementação do Delegate

  // MARK: - Clearsale liveness Delegate
    extension ViewController: CSLivenessDelegate {
        func liveness(didOpen: Bool) {
        }

        func liveness(error: CSLivenessError) {
        }

        func liveness(success: CSLivenessResult) {
        }
    }

Apps com landscape ativado

O SDK Liveness não suporta a funcionalidade de landscape e portanto é preciso aplicar as seguintes configurações:

AppDelegate

Criar variável do tipo booleana chamada lockOrientationToPortrait e sobrescrever o método supportedInterfaceOrientationsFor para desligar o landscape no momento em que iniciar o SDK. A seguir, trazemos um exemplo de AppDelegate e chamada do SDK:

Modelo de implementação do AppDelegate

import UIKit

class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?
    var lockOrientationToPortrait = false
    func application(_ application: UIApplication,didFinishLaunchingWithOptions
    launchOptions: [UIApplication.LaunchOptionsKey : Any]?)
    -> Bool {
        ...
    }

    func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
        if lockOrientationToPortrait {
            return .portrait
        }
        return .all
    }
}

Exemplo de implementação Liveness

IBAction func initLiveness(_ sender: Any) {
    force(portrait: true)
    DispatchQueue.global(qos: .userInitiated).asyncAfter(deadline: .now() + 2 ){
        DispatchQueue.main.async {
            self.livenessSdk = CSLiveness(
                CSLivenessConfig(...)
            )
            self.livenessSdk.delegate = self
            self.livenessSdk.start(viewController: self, animated: true);
        }
    }
}

Exemplo de implementação do CSLivenessDelegate

// MARK: - Clearsale liveness Delegate
extension ViewController: CSLivenessDelegate {
    func liveness(didOpen: Bool) {
    }

    func liveness(error: CSLivenessError?) {
        labelResult.text = error.debugDescription
        force(portrait: false)
    }

    func liveness(success: CSLivenessResult) {
        force(portrait: false)
    }

    private func force(portrait: Bool)  {
        if let delegate = UIApplication.shared.delegate as? AppDelegate {
            delegate.lockOrientationToPortrait = portrait
            UIDevice.current.setValue(UIInterfaceOrientation.portrait.rawValue,forKey: "orientation")
        }
    }
}

📘

Arquivo de Exemplo: clique aqui

Detalhes de privacidade

Uso de dados

Todas as informações coletadas pelo SDK da ClearSale são com exclusiva finalidade de prevenção à fraude e proteção ao próprio usuário, aderente à política de segurança e privacidade das plataformas Google e Apple e à LGPD. Por isso, estas informações devem constar na política de privacidade do aplicativo.

Tipo de dados coletados

O SDK da ClearSale coleta as seguintes informações do dispositivo :

  • Características físicas do dispositivo/ hardware (Como tela, modelo, nome do dispositivo);
  • Características de software (Como versão, idioma, build, controle parental);
  • Informações da câmera;