CLEARSALE

SDK IOS Liveness

v2.0.8

🚧

A partir da release 2.0.8 (08/10/2024), foi implementado um novo método opcional de autenticação via token resgatado da autenticação via Plataforma Data Trust. Recomenda-se que todos façam a alteração, pois, futuramente, será o único método. Para mais informações, confira a seção Exemplos.

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).

Requisitos mínimos

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

Instalação do Package

  • 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
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>

Classes

CSLiveness

Descrição

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.

CSLivenessConfig

Descrição

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

Construtores

Esta classe possui dois construtores públicos. São eles:

[RECOMENDADO] Construtor que utiliza o token da Plataforma Data Trust (08/10/2024)

ParâmetrosDescrição
accessToken: StringString que serve para autenticação. Este parâmetro é obtido realizando uma autenticação na Plataforma Data Trust. Para mais informações, acesse esse link .
transactionId: StringString que identifica a transação. Este parâmetro é obtido na geração da transaction na Plataforma Data Trust. Para mais informações, acesse esse link.
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].

[LEGADO] Construtor das versões 2.0.6 ou inferior

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].

CSLivenessColorsConfig

Descrição

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.

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(
       accessToken: "", //Obtido via https://datatrustapihml.clearsale.com.br/v1/authentication OU https://datatrustapi.clearsale.com.br/v1/authentication
       transactionId: "", //Obtido via https://datatrustapihml.clearsale.com.br/v1/transaction OU https://datatrustapi.clearsale.com.br/v1/transaction
       colors: colors //Opcional
     )

    self.livenessSdk = CSLiveness(configuration: configuration, vocalGuidance: bool)
    self.livenessSdk?.delegate = self
    self.livenessSdk?.start(viewController: self, animated: true);
    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;