SDK IOS

Última atualização: 24 de Outubro de 2023

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: 11.0 ou superior.
  • Versão do projeto Swift 4+: funciona com Xcode anterior ao 13.

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 desenvolvimento e testes

platform :ios, '12.0'

use_frameworks!

target 'NOME_DO_SEU_PROJETO' do
pod 'CSLivenessSDK', :git => 'URL DO REPOSITÓRIO ENVIADO PELA CLEARSALE', :tag => '1.2.3-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 => '1.2.3'
end

Obs: O PAT do iOS é junto com a Url do Repositório enviado 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:
  2. <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âmetros Descrição
CSLivenessConfigurations Objeto com as configurações que serão utilizadas pela instância do CSLiveness.
vocalGuidance Booleano para habilitar ou desabilitar áudios com falas humanas para guiar o usuário no processo de liveness.

Classe CSLivenessConfiguration

Descrição

CSLivenessConfiguration 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âmetros Descrição
clientId Id que identifica o cliente junto com a clear ClearSale (valor fornecido pela ClearSale).
clientSecret Token que funciona como autenticação para identificação do cliente a utilizar o serviço (valor fornecido pela ClearSale).
identifierId Identifier ID é uma string de até 100 caracteres OPCIONAL 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 É uma string de 11 caracteres OPCIONAL (no formato CPF) do usuário que irá realizar o fluxo, devendo seguir as regras de validade estipuladas pelo Governo.

Classe CSLivenessDelegate

Descrição

Para acesso a resposta do processamento da ClearSale ou erros durante o processo é disponibilizado o delegate CSLivenessDelegate.

Construtores

Esta classe não possui um construtor público.


Metodos
Nome do Metodo Descrição Obrigatoriedade
liveness(didOpen: Bool) Indica se o SDK foi aberto. Opcional
liveness(error: CSLivenessError) Houve erros no processamento interno do SDK. Requerido
liveness(success: CSLivenessResult) Sucesso no processamento interno do SDK. Requerido

Enum CSLivenessError

Descrição

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

Cases

Este enum possui os seguintes cases:


Nome do case Descrição
alreadyOpened O SDK já está aberto e foi feita uma nova chamada para abri-lo novamente.
authentication Falha na autenticação com os dados atribuídos no ClearsaleLivenessConfigurations.
background Indica que o app que contém o sdk passou a ser executado em background e por isso o sdk foi finalizado.
cameraInitializationIssue Falha ao inicializar câmera.
cameraPermissionDenied O Usuário não permitiu acesso à câmera.
landscapeModeNotAllowed Indica que o usuário rotacionou celular para landscape.
lowMemory Indica pouco recurso de memória no aparelho do usuário para processamento do liveness.
maxRetry Máximo de tentativas para tentar realizar a prova de vida.
network Erro de conexão de rede.
timeout O Usuário não interagiu com o liveness.
unexpected Indica que ocorreu um erro inesperado na execução do SDK.
userCancel Usuário cancelou a ação de liveness.
invalidIdentifierId Identifier Id inválido.
invalidCPF Cpf inválido.
none Aconteceu 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.


Propriedade Descrição
real: Bool Indica que a prova de vida foi concluída e se é uma pessoa real ou não.
sessionId: String Esse 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?
    ...
    self.livenessSdk = CSLiveness(
                configurations: CSLivenessConfigurations(
                    clientId: "SEU CLIENT ID AQUI",
                    clientSecret: "SEU SECRET ID AQUI",
                    identifierId: "IDENTIFIER DO CLIENTE AQUI",
                    cpf: "CPF DO CLIENTE AQUI"
                ),
                vocalGuidance: true
            )
    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

É preciso adicionar mais um passo em aplicativos que tenham suporte a opção de visualização no modo landscape. O SDK CSLiveness não suporta a funcionalidade de landscape e portanto é preciso fazer algumas 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 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(
                CSLivenessConfigurations(...)
            )
            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")
        }
    }
}

Aplicativo de Exemplo

Sample

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;

Algumas dessas informações podem vir a serem compartilhadas com nossas ferramentas de monitoria e error tracking.

Licença de Uso

Ao realizar o download e utilizar nosso SDK você estará concordando com a seguinte licença:

Copyright © 2024 ClearSale

Todos os direitos são reservados, sendo concedida a permissão para usar o software da maneira como está, não sendo permitido qualquer modificação ou cópia para qualquer fim. O Software é licenciado com suas atuais configurações “tal como está” e sem garantia de qualquer espécie, nem expressa e nem implícita, incluindo mas não se limitando, garantias de comercialização, adequação para fins particulares e não violação de direitos patenteados. Em nenhuma hipótese os titulares dos Direitos Autorais podem ser responsabilizados por danos, perdas, causas de ação, quer seja por contrato ou ato ilícito, ou outra ação tortuosa advinda do uso do Software ou outras ações relacionadas com este Software sem prévia autorização escrita do detentor dos direitos autorais.