Videoidentificação - VideoID

Introdução

A Captura Facial é realizada com o Componente VideoID.

Este componente é responsável por realizar a gravação de um usuário identificando-se, mostrando o rosto e seu Documento de identidade.

• Gerenciamento interno de câmeras, microfone e permissões.

• Conexão com os serviços.

• Leitura do OCR e captura do documento.

Na seção de Lançamento simplificado são detalhados os passos necessários para a integração básica do SDK. Nesta seção é adicionada a informação para o lançamento deste componente.

---

Dependência

A dependência específica do componente é:

implementation "com.facephi.androidsdk:video_id_component:$version"

---

Controladores disponíveis

Controlador	Descrição
VideoIdController	Controlador principal de videoidentificação
SignatureVideoIdController	Controlador para assinar um processo com uma Captura

---

Lançamento simplificado

Uma vez iniciado o SDK e criada uma nova operação, será possível iniciar o componente. Será possível usar qualquer um de seus controladores para executar sua funcionalidade.

Lançamento:

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

---

Configuração básica

Para lançar o componente atual, deverá ser criado um objeto VideoIdConfigurationData que será a configuração do controlador do componente.

A configuração básica necessária é a seguinte:

VideoIdConfigurationData(
    mode = VideoIdMode.DOCUMENT_FRONT_BACK,
)

Os diferentes modos são:

• VideoIdMode.ONLY_FACE

• VideoIdMode.FACE_DOCUMENT_FRONT

• VideoIdMode.FACE_DOCUMENT_FRONT_BACK

• VideoIdMode.DOCUMENT_FRONT

• VideoIdMode.DOCUMENT_FRONT_BACK

---

Recebimento do resultado

A execução retornará as informações no formato SdkResult. Sendo possível diferenciar entre uma execução correta e uma incorreta:

when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}

Recebimento de erros

Os erros serão retornados como um objeto 'VideoIdError'.

Lista de erros:

• VID_ACTIVITY_RESULT_MSG_ERROR: O resultado da atividade está incorreto

• VID_APPLICATION_CONTEXT_ERROR: O contexto de aplicação necessário é nulo

• VID_CANCEL_BY_USER: O usuário cancelou o processo

• VID_CANCEL_LAUNCH: Foi feito um cancelamento geral do SDK

• VID_COMPONENT_LICENSE_ERROR: A licença do componente não está correta

• VID_EMPTY_LICENSE: A String da licença está vazia

• VID_FACE_DETECTION_TIMEOUT: Não foi detectado rosto

• VID_FETCH_DATA_ERROR: Erro na obtenção do resultado

• VID_FLOW_ERROR: Erro no processo de fluxo

• VID_INITIALIZATION_ERROR: Erro de Inicialização

• VID_MANAGER_NOT_INITIALIZED: Os managers são nulos

• VID_NETWORK_CONNECTION: Erro na conexão com a internet

• VID_NO_DATA_ERROR: Os dados de entrada são nulos

• VID_OPERATION_NOT_CREATED: Não há nenhuma operação em andamento

• VID_PERMISSION_DENIED: O usuário rejeitou as permissões

• VID_SOCKET_ERROR: Erro na conexão dos serviços

• VID_TIMEOUT: Timeout no processo

• VID_VIDEO_ERROR: Erro no processamento do vídeo

• VID_VIDEO_CALL_ACTIVE: Não é possível iniciar porque já há uma Videochamada ativa

• VID_VIDEO_RECORDING_ACTIVE: Não é possível iniciar porque o processo de gravação de vídeo está ativo

Recebimento de execução correta - data

Na parte de SdkResult.Success - data, dispondremos da classe VideoIdResult.

O resultado retorna as imagens no formato SdkImage, é possível extrair o bitmap acessando image.bitmap. Se quiser converter para base64, é possível usar a função:

Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)

Os campos retornados no resultado são os seguintes:

frontDocumentData

Dados da frente do documento. Inclui:

• documentImage: Imagem do documento

• documentFullImage: Imagem completa capturada

• documentFaceImage: Se uma face for encontrada no documento, a imagem dela é retornada.

• iqaOverExposure: Valor numérico entre 0 e 1 que indica o nível de superexposição da imagem; um valor alto sugere que a imagem está iluminada demais, o que pode dificultar a leitura do documento.

• iqaReadable: Valor numérico entre 0 e 1 que indica a legibilidade do texto do documento; valores mais altos implicam que o texto está mais claro e fácil de reconhecer.

• iqaSharpness: Valor numérico entre 0 e 1 que indica a nitidez da imagem do documento; valores altos refletem uma imagem mais focada, o que melhora a capacidade de extração de dados.

• documentFaceImageTokenized: Se uma face for encontrada no documento, a imagem criptografada dela é retornada.

backDocumentData

Dados do verso do documento. Inclui:

• documentImage: Imagem do documento

• documentFullImage: Imagem completa capturada

• documentFaceImage: Se uma face for encontrada no documento, a imagem dela é retornada.

• iqaOverExposure: Valor numérico entre 0 e 1 que indica o nível de superexposição da imagem; um valor alto sugere que a imagem está iluminada demais, o que pode dificultar a leitura do documento.

• iqaReadable: Valor numérico entre 0 e 1 que indica a legibilidade do texto do documento; valores mais altos implicam que o texto está mais claro e fácil de reconhecer.

• iqaSharpness: Valor numérico entre 0 e 1 que indica a nitidez da imagem do documento; valores altos refletem uma imagem mais focada, o que melhora a capacidade de extração de dados.

• documentFaceImageTokenized: Se uma face for encontrada no documento, a imagem criptografada dela é retornada.

faceImage

Imagem do usuário capturada na primeira seção do processo.

ocrMap

Mapa do OCR extraído do documento.

ocrDiagnostic

Dicionário com o diagnóstico OCR do documento. As chaves são os campos a validar e os valores são instâncias de OcrDiagnostic.

Diagnóstico OCR extraído do documento.

• OK: O OCR está correto.

• NOT_FOUND: A chave OCR não foi encontrada.

• TOLERANCE_ERROR: O OCR não está correto.

• WARNING: O OCR não está correto, mas é apenas um aviso porque é um campo opcional.

matchingSidesScore

Valor numérico entre 0 e 1 que estima o nível de correspondência entre as faces do documento (frente e verso).

documentType

Tipo de documento obtido.

personalData

Conjunto reduzido de dados obtidos do usuário:

• issuer

• documentNumber

• issueDate

• expiryDate

• name

• surname

• fullName

• gender

• birthDate

• birthPlace

• nationality

• address

• nfcKey

• numSupport

• mrz

speechText

Texto que o usuário deverá pronunciar durante a gravação do vídeo.

faceImageTokenized

Imagem criptografada do usuário capturada na primeira seção do processo.

---

Informações avançadas

Esta seção amplia as informações do componente.

Configuração avançada do componente

Para iniciar o componente atual, deverá ser criado um objeto _VideoIdConfigurationData _ que será a configuração do controlador do componente.

Os campos incluídos na configuração (url, apiKey, tenantId), normalmente não é necessário que sejam informados pois são preenchidos internamente por meio da licença usada.

Esses campos geralmente são informados apenas quando o servidor es OnPremise.

url

Caminho para o socket de vídeo

apiKey

ApiKey necessária para a conexão com o socket de vídeo

tenantId

Identificador do tenant que faz referência ao cliente atual, necessário para a conexão com o serviço de vídeo.

sectionTime

Indica a duração das seções com tempo associado (Captura Facial e troca de câmera).

mode

• ONLY_FACE: O processo é realizado capturando o rosto do usuário.

• FACE_DOCUMENT_FRONT: O processo é realizado capturando o rosto do usuário e a parte frontal do Documento de identidade.

• FACE_DOCUMENT_FRONT_BACK: O processo é realizado capturando o rosto do usuário e o Documento de identidade completo.

• DOCUMENT_FRONT: O processo extrai as informações apenas da parte frontal do documento.

• DOCUMENT_FRONT_BACK: O processo extrai as informações apenas do documento completo.

timeoutServerConnection

Tempo máximo de espera em ms pela resposta do servidor.

sectionTimeout

Tempo máximo permitido para concluir uma seção (em ms).

autoFaceDetection

Ativa/desativa a detecção automática de rosto.

depuração

Habilita a exibição de informações adicionais úteis para o diagnóstico e acompanhamento do comportamento interno.

countryFilter

Permite restringir o processamento a um conjunto específico de países, aceitando um array de strings que representam os aliases em formato ISO3 (código de 3 letras segundo o padrão ISO 3166-1).

documentFilter

Permite restringir os tipos de documentos aceitos durante a captura. Os valores possíveis são:

• "IDC": Documento de identidade (ID Card)

• "PSP": Passaporte (Passport)

• "DLI": Licença de Condução (Driver License)

• "VIS": Visto (Visa)

• "FOC": Cartão de Estrangeiro (Foreign Card)

• "INV": Fatura (Invoice)

• "CUS": Documento personalizado (Custom Document)

speechText

Texto que o usuário deverá pronunciar durante a gravação do vídeo.

ocrValidations

Dicionário com as validações OCR a serem realizadas. As chaves são os campos a validar e os valores são instâncias de OcrValidationValue.

OcrValidationValue tem os seguintes campos:

• value: O valor a validar.

• tolerance: O nível de tolerância para a validação.

  • STRICT: Validação estrita.

  • LOW_TOLERANCE: Validação com baixa tolerância.

  • MEDIUM_TOLERANCE: Validação com tolerância média.

  • HIGH_TOLERANCE: Validação com alta tolerância.

• validationType: O tipo de validação a ser realizada.

  • OPTIONAL: Validação opcional.

  • REQUIRED: Validação obrigatória.

ocrMaxWarnings

Número máximo de avisos permitidos na validação OCR.

maxRetries

Número máximo de tentativas permitidas para a validação OCR. O valor padrão é 3.

---

Personalização do componente

Além das mudanças que podem ser feitas no nível do SDK (as quais são explicadas no documento de Personalização do SDK), este componente em específico permite a modificação de sua interface.

Textos

Os textos podem ser personalizados adicionando um arquivo XML de recursos no aplicativo cliente e sobrescrevendo os valores padrão.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Waiting -->
    <string name="video_widget_id_text_waiting_agent_title">Video ID</string>

    <!-- Process -->
    <string name="video_widget_id_document_front_message">Coloque a frente do seu documento nos marcadores</string>
    <string name="video_widget_id_document_front_message_readable">Mantenha a frente do seu documento nos marcadores</string>
    <string name="video_widget_id_document_front_message_not_readable">Aproxime a frente do seu documento dos marcadores</string>
    <string name="video_widget_id_document_back_message">Agora coloque o verso do seu documento</string>
    <string name="video_widget_id_document_back_message_readable">Mantenha o verso do seu documento nos marcadores</string>
    <string name="video_widget_id_document_back_message_not_readable">Aproxime o verso do seu documento dos marcadores</string>
    <string name="video_widget_id_switch_camera_message">Prepare o documento enquanto trocamos a câmera</string>
    <string name="video_widget_id_finish_button">CONCLUIR</string>
    <string name="video_widget_id_ready_button">CONTINUAR</string>
    <string name="video_widget_id_exit_alert_cancel">Cancelar</string>
    <string name="video_widget_id_exit_alert_question">Tem certeza de que deseja encerrar o processo?</string>
    <string name="video_widget_id_exit_alert_finish">Concluir</string>
    <string name="video_widget_id_exit_alert_accept">Aceitar</string>
    <string name="video_widget_id_close_button_alt">Fechar</string>
    <string name="video_widget_id_back_button_alt">Voltar</string>
    <string name="video_widget_id_logo_alt">Logo</string>
    <string name="video_widget_id_face_message">Posicione seu rosto dentro do quadro.</string>
    <string name="video_widget_id_multiple_face_message">Vários rostos detectados. Posicione apenas seu rosto dentro do quadro</string>
    <string name="video_widget_id_speech_message">Diga em voz alta: "Eu (nome e sobrenome) aceito os termos e condições".</string>
    <string name="video_widget_id_front_document_captured_message">Frente do documento capturada com sucesso</string>
    <string name="video_widget_id_document_back_finish_message">Verso do documento capturado com sucesso</string>

    <!-- Diagnostic -->
    <string name="video_widget_id_restart_button">GRAVAR NOVAMENTE</string>
    <string name="video_widget_id_timeout_title">Tempo excedido</string>
    <string name="video_widget_id_timeout_desc">Não foi possível concluir a gravação a tempo. Vamos tentar novamente.</string>
    <string name="video_widget_id_face_timeout_title">Não foi possível detectar seu rosto</string>
    <string name="video_widget_id_face_timeout_desc">Posicione seu rosto no marcador para iniciar o processo</string>
    <string name="video_widget_id_internal_error_title">Houve um problema técnico</string>
    <string name="video_widget_id_internal_error_desc">Pedimos desculpas. Ocorreu um erro inesperado. Tente novamente.</string>
    <string name="video_widget_id_ocr_error_desc">O documento não pôde ser lido. Verifique a iluminação e a distância até a câmera</string>
    <string name="video_widget_id_finish_message">Gravação de vídeo concluída!</string>
</resources>

Animações

Se desejar modificar as animações (lottie) do SDK, será necessário incluir as animações com o mesmo nome na pasta res/raw/ da aplicação.

video_id_anim_doc_and_face.json
video_id_anim_face.json
video_id_anim_loading.json

Visualizações externas

É possível modificar completamente as telas do componente mantendo sua funcionalidade e navegação. Para isso, devem ser implementadas as seguintes interfaces:

Tela de diagnóstico de erro:

interface IVideoIdErrorDiagnosticView {
    @Composable
    fun Content(
        error: VideoIdError,
        onRetry: () -> Unit,
        onClose: () -> Unit,
    )
}

Depois de criadas as classes que implementam as interfaces, no lançamento do componente será possível adicionar o parâmetro "customViews" para que sejam usadas no SDK.