🚧

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.

Como obter o accessToken e transactionId?

• accessToken: Faça a autenticação seguindo as instruções da API DataTrust e obtenha o token do retorno.
• transactionId: Crie uma transação seguindo as instruções da API DataTrust e obtenha o id do retorno.

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: 13.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 até a versão 3.0.3:

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.

🚧

A partir da versão 4.0.0, o SDK passa a utilizar um único pacote, unificando os ambientes de homologação e produção.
A terminação -hml foi removida, sendo utilizado apenas o pacote CSLivenessSDK:VERSION para ambos os ambientes.

Instalação à partir da versão 4.0.0:

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

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:

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 à partir da versão 4.0.0:

[LEGADO] Construtor das versões 3.0.3 à 2.0.8

CSLivenessColorsConfig

Descrição

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

Enum CSLivenessError

Descrição

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

Cases

Este enum possui os seguintes cases:

CSLivenessResult

Descrição

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

Propriedades

Esta classe possui as seguintes propriedades:

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
			environment:CSLivenessEnvironments.prd //altere para hml, caso queira esse ambiente
     )

    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(
       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);

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

Boas práticas para testes em ambiente de homologação (HML)

O ambiente de homologação foi desenvolvido exclusivamente para testes de integração e validação funcional entre sistemas. Para garantir estabilidade e performance adequadas a todos os clientes que utilizam este ambiente, seguem algumas orientações importantes:

• ❌ Não utilize o ambiente de HML para testes de carga ou stress.Testes com alto volume simultâneo devem ser realizados em ambientes controlados.
• ⏱️ O uso está limitado a 50 requisições por minuto.Acima desse limite, o sistema pode apresentar falhas, bloqueios temporários ou retornos inconsistentes.
• 📱 O teste é restrito a 5 dispositivos diferentes.Dispositivos excedentes podem gerar erro de limite, comprometendo os testes.

Seguindo essas práticas, evitamos impactos na análise dos testes e garantimos uma melhor experiência de uso para todos.

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;