Configurações avançadas

Introdução

Nesta seção, amplia-se a informação geral sobre o lançamento do SDK.

---

Informações avançadas do lançamento do SDK

Nesta seção, será ampliada a informação da seção "Lançamento simplificado do SDK".

Adicionar repositório privado

Por questões de segurança e manutenção, os novos componentes da SDKMobile são armazenados em repositórios privados que exigem credenciais específicas para acessá-los. Essas credenciais deverão ser obtidas por meio da equipe de suporte de Facephi.

Uma vez obtidas as credenciais, deverá ser incluído o seguinte trecho de código para configurar o repositório Maven no Gradle do seu projeto, ou no arquivo settings.gradle do mesmo. Recomenda-se incluí-lo após mavenCentral()

maven {
    Properties props = new Properties()
    def propsFile = new File('local.properties')
    if(propsFile.exists()){
        props.load(new FileInputStream(propsFile))
    }
    name="external"
    url = uri("https://facephicorp.jfrog.io/artifactory/maven-pro-fphi")
    credentials {
        username = props["artifactory.user"] ?: System.getenv("USERNAME_ARTIFACTORY")
        password = props["artifactory.token"] ?: System.getenv("TOKEN_ARTIFACTORY")
    }
}

Para que o projeto recupere corretamente as dependências, as credenciais (Usuário e Token) deverão estar configuradas corretamente

Há várias formas de configurar as credenciais de acesso ao repositório:

• Como variáveis de ambiente com o seguinte nome. Por exemplo:

  export USERNAME_ARTIFACTORY=YOUR_CREDENTIALS_USERNAME
  export TOKEN_ARTIFACTORY=YOUR_CREDENTIALS_TOKEN

  Se as dependências não forem reconhecidas ao sincronizar, elas devem ser incluídas por meio de variáveis de ambiente no arquivo:

~/.zshrc

• Incluídos no arquivo local.properties com a seguinte estrutura:

  artifactory.user=YOUR_CREDENTIALS_USERNAME
  artifactory.token=YOUR_CREDENTIALS_TOKEN

Inicialização do SDK

Deve-se evitar inicializar um controlador que não será usado.

O SDK funciona por meio de um controlador principal (SDKController) que deve ser inicializado corretamente para que se possa usar o restante da funcionalidade. Os passos a seguir na inicialização são:

1. Incluir o objeto Application por meio da classe SdkApplication.

2. Decidir se a licença será incluída por meio de um String ou com um serviço de licenciamento remoto (consultar seção 3.1).

3. O controlador TrackingController caso se queira conectar com a plataforma.

O ponto 3 é opcional e exigiria o uso do componente de Tracking (mais informações sobre este módulo em sua própria documentação).

Um exemplo de inicialização sem TrackingController seria o seguinte:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE")
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Um exemplo de inicialização com TrackingController seria o seguinte:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE"),
    trackingController = TrackingController(),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Injeção de licenças

Como mencionado anteriormente, atualmente existem duas formas de injetar a licença:

a. Obtendo a licença por meio de um serviço

Por meio de um serviço que simplesmente exigirá uma URL e um API-KEY como identificador. Isso evitaria problemas ao manipular a licença, assim como a constante substituição dessas licenças quando surgisse algum problema com ela (malformação ou modificação indevida, expiração da licença...)

Exemplo de implementação em Kotlin:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOnline(EnvironmentLicensingData(
            apiKey = "...")
      )),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Exemplo de implementação em Java:

SDKController.INSTANCE.initSdk(
    new SdkApplication(activity.getApplication()),
    new LicensingOnline(new EnvironmentLicensingData(
      apiKey = "...")),
    sdkResult ->
    {
      if (sdkResult instanceof SdkResult.Success) {
        Napier.d("APP: INIT SDK: OK")
      } else if (sdkResult instanceof SdkResult.Error) {
        Napier.d("APP: INIT SDK: KO - ${it.error}")
      }
    }
  );

b. Injetando a licença como String

A licença pode ser atribuída diretamente como uma String, da seguinte maneira:

Exemplo de implementação em Kotlin:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE"),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Exemplo de implementação em Java:

SDKController.INSTANCE.initSdk(
  new SdkApplication(activity.getApplication()),
  new LicensingOffline("LICENSE"),
  sdkResult ->
  {
    if (sdkResult instanceof SdkResult.Success) {
      Timber.d("APP: INIT SDK: OK")
    } else if (sdkResult instanceof SdkResult.Error) {
      Timber.d("APP: INIT SDK: KO - ${it.error}")
    }
  }
);

Recebimento de erros

Na parte do erro, teremos a classe SdkError.

Lista de erros:

• EMPTY_LICENSE: Licença vazia

• INIT_AI_MODELS(error: String): Erro obtido no serviço de download de modelos

• INIT_FLOW (error: String): Erro obtido no serviço de download de flow

• LICENSE_CHECKER_ERROR (error: String): Erro obtido ao verificar se a licença está correta

• LICENSING_ERROR (error: String): Erro obtido no serviço de download de licenças

• NETWORK_CONNECTION_ERROR: Erro de conexão com a internet

• TRACKING_ERROR (error: String): Erro obtido ao iniciar o controlador de Tracking

---

Iniciar nova operação

Sempre que se desejar iniciar o fluxo de uma nova operação (exemplos de operações seriam: Onboarding, Authentication, VideoCall,...) é essencial indicar ao SDKController que ela vai começar, e assim o SDK saberá que as próximas chamadas de Componentes (também chamados Steps) farão parte dessa operação.

Ao iniciar um processo ou fluxo, sempre deverá ser realizada a chamada ao método newOperation

Este método tem os seguintes parâmetros de entrada:

1. operationType: Indica se será feito um processo de ONBOARDING ou de AUTHENTICATION.

2. customerId: ID único do usuário, se houver (controlado no nível da aplicação)

   1. Este parâmetro aparecerá refletido para cada operação na plataforma.

3. steps: Lista de passos da operação, se tiverem sido definidos previamente

4. enableTracking: Permite ativar ou desativar o envio de eventos de Tracking para esta operação. Se não for informado, considera-se true.

Há 2 maneiras de realizar este início de operação, dependendo de se são conhecidos os passos que formarão o fluxo do processo de registro ou autenticação (caso os componentes sejam executados de forma sequencial e sempre da mesma maneira) ou, em caso contrário, de que o fluxo não esteja definido e seja desconhecido (por exemplo, o cliente final é quem decide a ordem de execução dos componentes).

• Fluxo conhecido (a operação aparecerá rastreada na plataforma com todos os passos da lista).

  Exemplo de implementação Kotlin:

val result = SDKController.newOperation(
        operationType = OperationType.ONBOARDING,
        customerId = "customer_id",
        steps = listOf(Step.SELPHI_COMPONENT, Step.SELPHID_COMPONENT),
        enableTracking = true)
when (result) {
    is SdkResult.Success -> {
        Timber.d("APP: NEW OPERATION OK")
        Timber.d("Session ID: ${result.data.sessionId}")
        Timber.d("Operation ID: ${result.data.operationId}")
    }
    is SdkResult.Error -> {
        Timber.d("APP: NEW OPERATION ERROR: ${result.error.name}")
    }
}

Exemplo de implementação Java:

 SDKController.INSTANCE.newOperation(
        OperationType.ONBOARDING,
        "customer_id",
        [Step.SELPHI_COMPONENT, Step.SELPHID_COMPONENT]
        ){
          if (sdkResult instanceof SdkResult.Success) {
            Napier.d("APP: NEW OPERATION: OK")
          } else if (sdkResult instanceof SdkResult.Error) {
            Napier.d("APP: NEW OPERATION: KO - ${it.error}")
          }
        }
  );

• Fluxo desconhecido (a operação aparecerá rastreada na plataforma com reticências). Exemplo de implementação Kotlin:

val result = SDKController.newOperation(
        operationType = OperationType.ONBOARDING,
        customerId = "customer_id",
        enableTracking = true)
when (result) {
    is SdkResult.Success -> {
        Timber.d("APP: NEW OPERATION OK")
    }
    is SdkResult.Error -> {
        Timber.d("APP: NEW OPERATION ERROR: ${result.error.name}")
    }
}

Exemplo de implementação Java:

 SDKController.INSTANCE.newOperation(
        OperationType.ONBOARDING,
        "customer_id"
        ){
          if (sdkResult instanceof SdkResult.Success) {
            Napier.d("APP: NEW OPERATION: OK")
          } else if (sdkResult instanceof SdkResult.Error) {
            Napier.d("APP: NEW OPERATION: KO - ${it.error}")
          }
        }
  );

sdkResult → Contém em data as informações da operação criada.

Quando o resultado é correto, data é um OperationResult com:

Campo	Descrição
sessionId	Identificador da sessão criada ou recuperada pelo SDK.
operationId	Identificador da operação ativa.
type	Tipo de operação iniciado (ONBOARDING ou AUTHENTICATION).
customerId	Identificador do usuário associado à operação.

Uma vez criada a operação os componentes do SDK associados a esta operação poderão ser executados. Consulte a documentação específica de cada componente para saber como fazer isso.

Tipos de operação existentes

Atualmente, existem as seguintes operações, durante as quais são usados determinados Componentes (STEPS).

A seguir, é apresentada uma tabela com a relação entre operações e steps:

Operação (OperationType)	Componente (Step)	Descrição
ONBOARDING	SELPHI_COMPONENT\nSELPHID_COMPONENT	- Validação facial de uma selfie contra o rosto de um documento\n- Extração do OCR do documento\n- Detecção de vivacidade
AUTHENTICATION	SELPHI_COMPONENT	- Validação facial por meio de templates\n- Detecção de vivacidade

Esta lista será ampliada em próximas atualizações do SDK, à medida que novos componentes e casos de uso forem surgindo.

Se a criação de uma nova operação devolver um erro do tipo INTERNAL_ERROR isso se deve principalmente a um problema de segurança. Para investigar a causa, é possível recuperar o Token associado ao erro, o qual fornece informações adicionais para sua análise.

if (result.error is SdkError.INTERNAL_ERROR){
    val token = (result.error as SdkError.INTERNAL_ERROR).error
}

---

Segurança

O SDK de Android incorpora um sistema de segurança destinado a detectar e bloquear ambientes potencialmente pouco confiáveis ou que possam indicar tentativas de ataque.

Este mecanismo está habilitado por padrão, permite identificar situações que poderiam comprometer a segurança e evita a execução do SDK em contextos que não são considerados seguros:

SDKController.securityMode(enable: Boolean) 

---

Lançamento de componentes

A funcionalidade do SDK é dividida em diferentes componentes com controladores específicos. Esses controladores serão “lançados” a partir do controlador geral.

Uma vez criada a nova operação (seção 3), poderão ser lançados os diferentes controladores do SDK. Para consultar essas informações, deverá-se acessar a documentação de cada um dos componentes específicos.

Exemplo de lançamento em Kotlin:

val result = SDKController.launch(ExampleController(ConfigurationData()))
when (result) {
    is SdkResult.Success -> {
        //Result OK
        result.data
    }
    is SdkResult.Error -> {
        //Result KO
        result.error.name
    }
}

Exemplo de lançamento em Java:

SDKController.INSTANCE.launch(
    new ExampleController(new ConfigurationData()) {
        if (sdkResult instanceof SdkResult.Success) {
            //Result OK
            it.data
          } else if (sdkResult instanceof SdkResult.Error) {
            //Result KO
            it.error.name
          }
    }
)

Opções para o lançamento do componente

Uma vez iniciado o SDK e criada uma nova operação, o componente poderá ser lançado. Há duas formas de lançá-lo:

• [COM Tracking] Esta chamada permite lançar a funcionalidade do componente normalmente, mas os eventos internos serão enviados ao servidor de tracking:

val response = SDKController.launch(
    ExampleController(SConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

• [SEM Tracking] Esta chamada permite lançar a funcionalidade do componente normalmente, mas nenhum evento será enviado ao servidor de tracking:

val response = SDKController.launchMethod(
    ExampleController(ConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

O método launch deve ser usado por padrão. Este método permite utilizar tracking caso o componente esteja ativado, e não o usará quando estiver desativado (ou quando o componente não estiver instalado).

Por outro lado, o método launchMethod cobre um caso especial, no qual o integrador tem o Tracking instalado e ativado, mas em um Fluxo determinado dentro da aplicação não deseja rastrear informações. Nesse caso, usa-se este método para evitar que essas informações sejam enviadas à plataforma.

---

Retorno do resultado

O resultado de cada componente será retornado por meio do SDK, mantendo sempre a mesma estrutura por meio da classe SdkResult cuja classe é uma Sealed Class que pode ter 2 estados possíveis:

• SdkResult.Success: Indica que a operação foi finalizada corretamente e contém internamente:

  • data: Contém o tipo de dado necessário de acordo com o processo/componente lançado.

• SdkResult.Error

  • error: Contém o tipo de erro necessário de acordo com o processo/componente lançado.

Na documentação de cada componente específico, serão detalhados os diferentes campos que este objeto pode retornar

Exemplo de uso:

when (result) {
    is SdkResult.Success -> {
        Napier.d("Selphi: OK")
        // SelphiResult:
        // result.data.bestImage
    }

    is SdkResult.Error -> Napier.d("Selphi: KO - ${result.error.name}")
}

---

Controladores auxiliares

Nesta seção, incluem-se outros controladores e operações auxiliares, alguns deles opcionais, e que podem ser necessários para a correta finalização do Fluxo.

Esses campos são necessários para a comunicação com o serviço de Facephi, caso se queira realizar qualquer verificação e desejar realizar o tracking de uma operação determinada.

Obtenção do OperationId

val result = SDKController.launch(GetOperationIdController())
Napier.d("Operation ID ${result}")

Obtenção do OperationType

val result = SDKController.launch(GetOperationTypeController())
Napier.d("Operation type ${result}")

Obtenção do SessionId

val result = SDKController.launch(GetSessionIdController())
Napier.d("Session ID ${result}")

Obtenção do CustomerID

val result = SDKController.launch(GetCustomerIdController())
Napier.d("Customer ID ${result}")

Atribuição do CustomerID

SDKController.launch(CustomerIdController("CustomerId"))

---

Opções de depuração e controle de erros

Há certas opções no SDK que permitem um aumento nos logs de depuração para verificar se tudo funciona corretamente.

Controle de erros nas conexões de Tracking com a plataforma

Uma vez que o SDK tenha sido iniciado corretamente, podem ser aplicados certos ajustes para obter mais informações sobre possíveis erros em Tracking; é possível fazer um acompanhamento por meio deste lançamento de controlador:

SDKController.launch(TrackingErrorController {
    Napier.d("Tracking Error: ${it.name}")
})

Ativação de logs gerais de depuração

 if (BuildConfig.DEBUG) {
  SDKController.enableDebugMode()
 }

---

Acompanhamento e análise de eventos na aplicação

A funcionalidade de eventos permite registrar e interpretar interações-chave dentro da aplicação, como mudanças de tela e ações do usuário, facilitando a análise do comportamento em tempo real.

Cada evento é enviado com um carimbo de data e hora, tipo e detalhe específico, proporcionando um acompanhamento estruturado e otimizando a experiência do usuário com dados precisos e acionáveis.

 SDKController.getAnalyticsEvents { time, componentName, eventType, info ->
            Log.i { "EVENTS", "*** $time - ${componentName.name} -" +
                " ${eventType.name} -  ${info ?: \"\"} " }
        }