Captura de impressões digitais - Phingers

Introdução

A captura de impressão digital é realizada por meio do Componente Phingers.

Este componente é responsável por capturar as impressões digitais do usuário (impressões digitais) e extrair os templates biométricos associados. Seus principais processos são:

• Gerenciamento interno da câmera e das permissões.

• Diferentes modos de extração: mão completa (quatro dedos sem o polegar), polegar ou dedos individuais.

• Detecção de vivacidade integrada.

• Assistência guiada durante o processo de captura.

• Geração de templates biométricos, imagens e métricas de qualidade.

Na seção Lançamento simplificado são descritos os passos necessários para a integração básica do SDK. Nesta página é adicionada a informação específica para o uso deste componente.

---

Dependência

A dependência específica do componente é:

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

---

Controladores disponíveis

Controlador	Descrição
PhingersTFController	Controlador principal de captura de impressões digitais
FPhingersTFController	Controlador principal de captura de impressões digitais para integrações de flow

Lançamento simplificado

Uma vez iniciado o SDK e criada uma nova operação, o componente de captura de impressões digitais pode ser acionado usando seu controlador.

Inicialização da captura:

val response = SDKController.launch(
    PhingersTFController(PhingersConfigurationData(...))
)
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, é necessário criar um objeto PhingersConfigurationData, que define a configuração do processo de captura.

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

PhingersConfigurationData(
    reticleOrientation = CaptureOrientation.LEFT,
    fingerFilter       = FingerFilter.SLAP,
    templateType       = TemplateType.NIST_TEMPLATE
)

Orientação da captura

Define a mão a ser capturada:

• CaptureOrientation.LEFT

• CaptureOrientation.RIGHT

Filtros de dedos

Permite definir quais dedos são capturados durante o processo:

• FingerFilter.SLAP

• FingerFilter.ALL_4_FINGERS_ONE_BY_ONE

• FingerFilter.ALL_5_FINGERS_ONE_BY_ONE

• FingerFilter.INDEX_FINGER

• FingerFilter.MIDDLE_FINGER

• FingerFilter.RING_FINGER

• FingerFilter.LITTLE_FINGER

• FingerFilter.THUMB_FINGER

Opções de TemplateType:

• NIST_TEMPLATE

• ISO_TEMPLATE

• NIST_T5_TEMPLATE

---

Recebimento do resultado

O lançamento do componente retorna um resultado no formato SdkResult, que pode corresponder a uma execução bem-sucedida ou a um erro.

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

---

Recebimento de erros

Os erros são retornados como um objeto PhingersError.

Lista de erros

• PHG_ACTIVITY_RESULT_ERROR: O resultado da atividade está incorreto.

• PHG_ACTIVITY_RESULT_MSG_ERROR: A mensagem do resultado da atividade está incorreta.

• PHG_APPLICATION_CONTEXT_ERROR: O contexto da aplicação é nulo.

• PHG_CANCEL_BY_USER: O usuário cancelou o processo.

• PHG_CANCEL_LAUNCH: Cancelamento geral do SDK.

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

• PHG_EMPTY_LICENSE: A string de licença está vazia.

• PHG_FETCH_DATA_ERROR: Erro na coleta do resultado.

• FLOW_ERROR: Erro no processo de flow.

• PHG_INITIALIZATION_ERROR: Erro de inicialização.

• PHG_INTERNAL_ERROR: Erro interno.

• PHG_LOW_QUALITY: Baixa qualidade da imagem.

• PHG_MANAGER_NOT_INITIALIZED: Os managers são nulos ou não estão inicializados.

• PHG_NO_DATA_ERROR: Nenhum dado da captura foi recebido.

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

• PHG_PERMISSION_DENIED: O usuário recusou as permissões.

• PHG_AUTOFOCUS_FAILURE: Falha no autofocus.

• PHG_CAMERA_FAILURE: Falha na câmera.

• PHG_CAPTURE_FAILURE: Falha na captura.

• PHG_CONFIGURATION_FAILURE: Erro de configuração.

• PHG_FINGERPRINT_CAPTURE_FAILURE: Falha na captura de impressões digitais.

• PHG_FINGERPRINT_TEMPLATE_IO_ERROR: Falha de IO do template.

• PHG_LICENSING_FAILURE: Erro de licença.

• PHG_LIVENESS_FAILURE: Erro no teste de vida.

• PHG_NO_FINGERS_DETECTED: Nenhuma impressão digital foi detectada.

• PHG_UNIQUE_USER_ID_NOT_SPECIFIED: Usuário não especificado.

• PHG_TIMEOUT: Timeout no processo.

• PHG_FLOW_VIDEO_RECORDING_ERROR: Erro na gravação de vídeo do flow.

• PHG_FLOW_TRACKING_ERROR: Erro de tracking no flow.

• PHG_TRACKING_STEP_ERROR: Erro na etapa de tracking.

---

Recepção do resultado correto - data

Em caso de sucesso, o campo data contém um objeto PhingersResult.

As imagens são retornadas como SdkImage. É possível obter o Bitmap por meio de image.bitmap. Para converter uma imagem em Base64, pode-se utilizar:

Base64.encodeToString(byteArray, Base64.NO_WRAP)

Campos retornados

• fingers: Lista de FingerResponse (uma entrada por dedo capturado)

• slapImages: Lista de SlapResponse (capturas slap quando aplicável)

• livenessScore: Média da pontuação de vivacidade (nullable)

• recording: Metadados da gravação local opcional quando videoRecordingEnabled=true e o widget gera um arquivo MP4. Pode ser null.

FingerResponse

• position: Índice de posição do dedo

• wsq: Imagem WSQ (ByteArray)

• displayImage: Imagem de exibição (ByteArray, PNG)

• minutiaesNumber: Número de minutiae detectadas

• quality: Pontuação de qualidade

• nistQuality: Pontuação de qualidade NIST

• nist2Quality: Pontuação de qualidade NIST2

• template: Template de impressão digital (ByteArray)

• proprietaryQuality: Qualidade proprietária do fornecedor

• templateType: Identificador do tipo de template

• imageWidth: Largura da imagem em pixels

• imageHeight: Altura da imagem em pixels

SlapResponse

• position: Índice da posição do slap

• image: Imagem slap (ByteArray)

VideoRecordingResult

• path: Caminho completo do arquivo de vídeo gerado.

• fileName: Nome do arquivo de vídeo.

• mimeType: Tipo MIME do arquivo. Por padrão video/mp4.

• sizeBytes: Tamanho do arquivo em bytes, quando o widget informa.

• durationMs: Duração do vídeo em milissegundos, quando o widget informa.

---

Informações avançadas

Configuração avançada do componente

O objeto PhingersConfigurationData permite personalizar o comportamento do componente.

Parâmetros disponíveis

reticleOrientation

Define o modo de detecção de impressões digitais e indica quais dedos serão detectados durante o processo. Os valores permitidos são:

• LEFT: A captura é ativada da mão esquerda.

• RIGHT: A captura é ativada da mão direita.

fingerFilter

Filtro para escolher a mão inteira ou um dedo específico: SLAP, INDEX_FINGER, MIDDLE_FINGER, RING_FINGER, LITTLE_FINGER, THUMB_FINGER.

templateType

Define o formato do template a ser gerado (variantes NIST/ISO).

useLiveness

Ativa ou desativa o detector de vivacidade durante o processo de captura de impressões digitais. Por padrão ele está em true.

extractionTimeout

Define um tempo de extração.

showPreviousTip

Mostra uma tela anterior ao lançamento da captura com informações sobre o processo a ser realizado e um botão para o lançamento.

showTutorial

Indica se o componente ativa a tela de tutorial. Nessa visualização é explicado de forma intuitiva como a captura é realizada.

showDiagnostic

Exibir telas de diagnóstico ao final do processo.

threshold

O parâmetro configura um captureQualityThreshold, para definir um threshold de qualidade para realizar a captura. O SDK limita esse valor ao intervalo 0.0-1.0.

showEllipses

Mostra as elipses durante a captura.

cropWidth

Indica uma largura para realizar um recorte da captura.

cropHeight

Indica uma altura para realizar um recorte da captura.

vibrationEnabled

Ativa a vibração. Por padrão true.

enableFlash

Ativa ou desativa o flash da câmera durante o processo de captura de impressões digitais. Por padrão ele está em true.

reticle

Identificador opcional do retículo. Por padrão "R_S".

showPreviousFingerSelector

Mostra o seletor de dedos antes da captura.

fingerSelectorHandOrientation

Define qual(is) mão(s) são exibidas no seletor (LEFT, RIGHT, BOTH).

fingerSelectorOptions

Define a lista de filtros que são exibidos no seletor. Se estiver vazia, o SDK usa: ALL_4_FINGERS_ONE_BY_ONE, SLAP, INDEX_FINGER.

licenseKey

Chave de licença opcional que é passada ao widget Phingers TF quando são usadas ativação ou licenciamento específico.

product

Produto opcional associado à ativação ou ao licenciamento do widget.

operationId

Identificador opcional de operação que é enviado ao widget para rastreabilidade e associação da captura.

videoRecordingEnabled

Ativa a gravação local opcional durante a captura de impressões digitais. Por padrão false.

videoRecordingDirectoryPath

Diretório de destino opcional para o arquivo de vídeo gerado.

videoRecordingFileName

Nome de arquivo opcional para a gravação gerada.

videoRecordingQuality

Qualidade da gravação local. Os valores permitidos são LOW, MEDIUM e HIGH. Por padrão MEDIUM.

---

Personalização do componente

Além das alterações 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 na aplicação cliente e sobrescrevendo os valores padrão.

<!-- Dica anterior -->
    <string name="phingers_widget_tip_title">Captura de Impressão Digital</string>
    <string name="phingers_widget_tip_message">Coloque seu dedo dentro da marca</string>
    <string name="phingers_widget_tip_message_alt">Coloque seu dedo dentro da marca</string>
    <string name="phingers_widget_tip_button">Começar</string>
    <string name="phingers_widget_tip_button_alt">Começar captura de impressão digital</string>
    <string name="phingers_widget_tip_close_button_alt">Voltar</string>
    <string name="phingers_widget_tip_info_button_alt">Ver dicas</string>
    <string name="phingers_widget_tip_anim_desc">Animação de instruções para a captura de impressão digital</string>
    <!-- Dica anterior (tipos específicos) -->
    <string name="phingers_widget_tip_title_left_slap">Impressões digitais da mão esquerda</string>
    <string name="phingers_widget_tip_message_left_slap">Junte os dedos. Aproxime ou afaste a mão até que suas impressões digitais fiquem em foco.</string>
    <string name="phingers_widget_tip_title_right_slap">Impressões digitais da mão direita</string>
    <string name="phingers_widget_tip_message_right_slap">Junte os dedos. Aproxime ou afaste a mão até que suas impressões digitais fiquem em foco.</string>
    <string name="phingers_widget_tip_title_left_finger">Impressões digitais da mão esquerda</string>
    <string name="phingers_widget_tip_message_left_finger">Foque o dedo indicador no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <string name="phingers_widget_tip_title_right_finger">Impressões digitais da mão direita</string>
    <string name="phingers_widget_tip_message_right_finger">Foque o dedo indicador no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <string name="phingers_widget_tip_title_thumb">Impressão digital do polegar</string>
    <string name="phingers_widget_tip_message_thumb">Foque o dedo polegar no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <!-- Seletor de dedos -->
    <string name="phingers_widget_selector_hand_question">Qual mão você usará?</string>
    <string name="phingers_widget_selector_hand_left">Esquerda</string>
    <string name="phingers_widget_selector_hand_right">Direita</string>
    <string name="phingers_widget_selector_secondary_question">Quais impressões digitais você quer escanear?</string>
    <string name="phingers_widget_selector_option_index">Dedo indicador</string>
    <string name="phingers_widget_selector_option_middle">Dedo médio</string>
    <string name="phingers_widget_selector_option_ring">Dedo anelar</string>
    <string name="phingers_widget_selector_option_little">Dedo mindinho</string>
    <string name="phingers_widget_selector_option_thumb">Dedo polegar</string>
    <string name="phingers_widget_selector_option_all4">4 dedos (indicador, médio, anelar e mindinho)</string>
    <string name="phingers_widget_selector_option_all4_sequence">4 dedos (um a um)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 dedos (um a um)</string>
    <string name="phingers_widget_selector_primary_button">Continuar</string>
    <!-- Captura -->
    <string name="phingers_widget_capture_close_button_alt">Voltar</string>
    <!-- Tutorial -->
    <string name="phingers_widget_tutorial_message_1">Posicione seu rosto no centro e olhe diretamente para a câmera.</string>
    <string name="phingers_widget_tutorial_message_2">Remova qualquer item que cubra seu rosto.</string>
    <string name="phingers_widget_tutorial_message_3">Procure um ambiente bem iluminado, sem sombras sobre o rosto.</string>
    <string name="phingers_widget_tutorial_message_1_anim_desc">A foto é tirada quando a pessoa está no centro.</string>
    <string name="phingers_widget_tutorial_message_2_anim_desc">Uma pessoa tira os óculos escuros e afasta o cabelo dos olhos.</string>
    <string name="phingers_widget_tutorial_message_3_anim_desc">A imagem aparece escura e uma pessoa acende a luz.</string>
    <string name="phingers_widget_tutorial_close_button_alt">Voltar ao tutorial anterior</string>
    <!-- Confirmação -->
    <string name="phingers_widget_image_captured">Imagem capturada</string>
    <string name="phingers_widget_confirmation_message">Sua foto parece clara e nítida?</string>
    <string name="phingers_widget_confirmation_retry">Tentar novamente</string>
    <string name="phingers_widget_confirmation_continue">Continuar</string>

    <!-- Status da câmera (ES) -->
    <string name="phingers_widget_camera_status_position_fingers">Coloque seus dedos dentro da marca</string>
    <string name="phingers_widget_camera_status_processing">Processando…</string>
    <string name="phingers_widget_camera_status_too_far">Aproxime a mão</string>
    <string name="phingers_widget_camera_status_too_close">Afaste a mão</string>
    <string name="phingers_widget_camera_status_low_focus">Mova o dedo para focar</string>
    <string name="phingers_widget_camera_status_good_focus">Mantenha o dedo parado</string>
    <string name="phingers_widget_camera_status_wrong_angle">Posicione o dedo na vertical</string>
    <string name="phingers_widget_camera_status_too_few">O dedo não foi detectado</string>
    <string name="phingers_widget_camera_status_too_many">Vários dedos detectados</string>
    <string name="phingers_widget_camera_status_wrong_hand_left">Você deve colocar o dedo da mão esquerda</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">Você deve colocar o dedo da mão direita</string>
    <string name="phingers_widget_camera_status_error">Erro na captura</string>
    <string name="phingers_widget_camera_status_timeout">Tempo de captura esgotado</string>
    <string name="phingers_widget_camera_status_success">Impressão digital capturada!</string>
    <string name="phingers_widget_camera_status_keep_hand_steady">Mantenha a mão firme</string>
    <string name="phingers_widget_timeout_desc">A captura excedeu o tempo limite. Tente novamente.</string>

    <!-- Dica dinâmica do dedo (ES) -->
    <!-- %1$s = lado (esquerdo/direito), %2$s = dedo (indicador/médio/anelar/mindinho/polegar) -->
    <string name="phingers_widget_hint_place_finger_mark">Coloque seu %2$s %1$s dentro da marca</string>
    <string name="phingers_widget_side_left">esquerdo</string>
    <string name="phingers_widget_side_right">direito</string>
    <string name="phingers_widget_finger_index">indicador</string>
    <string name="phingers_widget_finger_middle">médio</string>
    <string name="phingers_widget_finger_ring">anelar</string>
    <string name="phingers_widget_finger_little">mindinho</string>
    <string name="phingers_widget_finger_thumb">polegar</string>

Animações

As animações do componente são Lottie (JSON).

Para substituí-las, adicione os arquivos com o mesmo nome na pasta res/raw/ da aplicação:

phingers_anim_left.json
phingers_anim_left_finger.json
phingers_anim_right.json
phingers_anim_right_finger.json
phingers_anim_success.json
phingers_anim_thumb.json
phingers_anim_thumb_left.json
phingers_anim_thumb_right.json
phingers_anim_thumbs.json

Se não forem incluídas animações personalizadas, as animações padrão serão usadas.

---