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:
- 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âmetros | Descrição |
---|---|
configuration: CSLivenessConfig | Objeto com as configurações que serão utilizadas pela instância do CSLiveness. |
vocalGuidance: bool | Booleano 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âmetros | Descrição |
---|---|
accessToken: String | String 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: String | String 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: CSLivenessColorsConfig | Classe 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âmetros | Descrição |
---|---|
clientId: String | Identifica o cliente junto com a ClearSale (valor fornecido pela ClearSale). |
clientSecret: String | Token que funciona como autenticação para identificação do cliente a utilizar o serviço (valor fornecido pela ClearSale). |
identifierId: String | String 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: String | String de 11 caracteres (no formato CPF) do usuário que irá realizar o fluxo, devendo seguir as regras de validade estipuladas pelo Governo. |
colors: CSLivenessColorsConfig | Classe 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âmetro | Descrição |
---|---|
primaryColor: UIColor | Cor definida para atuar como PrimaryColor |
secondaryColor: UIColor | Cor definida para atuar como SecondaryColor |
titleColor: UIColor | Cor definida para atuar como TitleColor |
paragraphColor: UIColor | Cor 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 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. |
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?
...
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
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
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;
Updated 3 days ago