Captura de documentos - SelphID
Introdução
A captura de documentos é realizada por meio do Componente SelphID.
Este componente é responsável por capturar documentos de identidade e analisar as informações obtidas. Durante o processo, realizam-se, entre outros, os seguintes passos:
Gestão interna de câmeras e permissões.
Assistência guiada durante a captura do frente e verso do documento.
Extração das informações contidas no documento.
Obtenção de imagens do documento e de elementos associados:
Rosto do usuário.
Assinatura do usuário.
Alto nível de configuração:
Países.
Idiomas.
Tipos de documento.
Na seção Lançamento simplificado descrevem-se os passos básicos para a Integração do SDK. Nesta página detalha-se a informação específica necessária para iniciar e configurar este componente.
Dependência
A dependência específica do componente é:
Controladores disponíveis
Controlador
Descrição
SelphIDController
Controlador principal de reconhecimento de documentos
Lançamento simplificado
Uma vez iniciado o SDK e criada uma nova operação, o componente pode ser iniciado usando seu controlador.
Lançamento da Captura Facial:
Configuração básica
Para iniciar o componente é necessário criar um objeto SelphIDConfigurationData, que define o comportamento do Widget.
Na configuração básica:
É obrigatório definir o país e o tipo de documento.
No campo
specificDatadeve-se indicar o código de país correspondente (por exemplo,ESpara a Espanha).
Tipos de documento disponíveis
Recebimento do resultado
O resultado da inicialização é retornado como um objeto SdkResult, que pode indicar um resultado correto ou um erro.
Recebimento de erros
Os erros são retornados como um objeto SelphIdError.
Lista de erros
SPD_ACTIVITY_RESULT_ERROR: O resultado da atividade está incorreto.
SPD_ACTIVITY_RESULT_MSG_ERROR: O resultado da atividade recebido no msg está incorreto.
SPD_APPLICATION_CONTEXT_ERROR: O contexto de aplicação necessário é nulo.
SPD_BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Configuração do extrator incorreta
SPD_CAMERA_PERMISSION_DENIED: O usuário recusou as permissões.
SPD_CANCEL_BY_USER: O usuário cancelou o processo.
SPD_CANCEL_LAUNCH: Foi feita uma cancelação geral do SDK.
SPD_COMPONENT_LICENSE_ERROR: A licença do componente não está correta.
SPD_CONTROL_NOT_INITIALIZATED_ERROR: Widget: Erro de inicialização
SPD_EMPTY_LICENSE: O String de Licença está vazio.
SPD_EXTRACTION_LICENSE_ERROR: Widget: Erro de licença
SPD_FETCH_DATA_ERROR: Erro na coleta do resultado.
SPD_FLOW_ERROR: Erro no processo de flow.
SPD_HARDWARE_ERROR: Widget: Erro de hardware
SPD_INITIALIZATION_ERROR: Erro de inicialização.
SPD_MANAGER_NOT_INITIALIZED: Os managers estão nulos.
SPD_MOVE_FAIL: O usuário não se moveu conforme especificado no processo.
SPD_NO_DATA_ERROR: Os dados de entrada estão nulos.
SPD_OPERATION_NOT_CREATED: Não há nenhuma operação em andamento.
SPD_RESOURCES_NOT_FOUND: Não foi encontrado o zip de recursos
SPD_SETTINGS_PERMISSION_ERROR: Widget: Erro de permissões
SPD_TIMEOUT: Timeout no processo.
SPD_UNEXPECTED_CAPTURE_ERROR: Widget: Erro na captura
SPD_UNKNOWN_ERROR: Erro desconhecido
SPD_WIDGET_RESULT_DATA_ERROR: Erro nos dados de saída do Widget
Recebimento do resultado correto - data
Quando o resultado é correto (SdkResult.Success), obtém-se um objeto SelphIDResult.
As imagens são retornadas no formato SdkImage.
É possível acessar o bitmap por meio de image.bitmap.
Para converter uma imagem para Base64:
Campos retornados
frontDocument / tokenFrontDocument:
A imagem frontal do documento processada, limpa e recortada pelas bordas e seu token correspondente.
backDocument / tokenBackDocument
A imagem traseira do documento processada, limpa e recortada pelas bordas e seu token associado.
faceImage / tokenFaceImage
A imagem do rosto que foi encontrada no documento, caso exista, e seu token associado.
Válida para o processo de Matching facial.
documentCaptured
Esta propriedade indica o modelo de documento que foi capturado quando se realiza uma busca em modo SMSearch. Dessa forma, a aplicação pode saber qual modelo, entre todos os permitidos, foi detectado.
matchingSidesScore
Esta propriedade retorna um cálculo da similaridade dos dados lidos entre a frente e o verso do documento. O cálculo é realizado verificando a similaridade entre os campos comuns lidos em ორივas as faces. O resultado do cálculo será um valor entre 0,0 e 1,0 caso existam campos comuns no documento. Quanto maior for o valor, mais similares são os dados comparados. Se o cálculo retornar -1,0, é porque o documento não contém campos comuns ou ainda não há informação das duas faces.
Propiedad captureProgress
Esta propriedade retorna o estado em que o processo de captura se encontrava quando o Widget terminou. Estes são os possíveis valores:
0: Na leitura da frente, o Widget terminou sem conseguir detectar nada. Geralmente quando nenhum documento é colocado.
1: Na leitura da frente, o Widget terminou tendo detectado parcialmente um documento. Nesse caso, alguns dos elementos esperados conseguiram ser detectados, mas não todos os necessários.
2: Na leitura da frente, o Widget terminou tendo completado a detecção de todos os elementos do documento. Se o Widget termina nesse estado é porque a análise de OCR não pôde ser concluída com sucesso.
3: Na leitura da frente, o Widget terminou tendo analisado e extraído todo o OCR do documento. Esse é o estado em que terminaria uma leitura correta da frente de um documento.
Os estados do 4 ao 7 são exatamente iguais, apenas se referem ao resultado do processo quando o verso é analisado.
ocrResults
Este dicionário contém todos os dados detectados no documento. As chaves de cada campo estão codificadas de tal forma que a própria chave contém informação de onde o valor foi obtido. Assim, por exemplo, a chave Front/MRZ/DocumentNumber indica o valor do DocumentNumber que foi lido na frente do documento e na região do MRZ. Essas chaves dependem do documento capturado e, portanto, serão diferentes entre distintos países e modelos de documento. O dicionário também contém chaves com nomes mais genéricos e que não levam informação relativa à localização. Essas chaves contêm o dado mais completo de todos os lidos para esse campo.
Essas chaves são as seguintes:
FirstName: O valor associado a esta chave contém o nome do usuário.
LastName: O valor associado a esta chave contém os sobrenomes do usuário.
DateOfBirth: O valor associado a esta chave contém a data de nascimento detectada no documento.
Gender: O valor associado a esta chave contém o sexo do usuário detectado no documento.
Nationality: O valor associado a esta chave contém a nacionalidade do usuário detectado no documento.
DocumentNumber: O valor associado a esta chave contém o número do documento.
DateOfExpiry: O valor associado a esta chave contém a data de expiração do documento.
Issuer: O valor associado a esta chave contém o emissor do documento.
DateofIssue: O valor associado a esta chave contém a data de emissão do documento.
PlaceOfBirth: O valor associado a esta chave contém o local de nascimento do usuário.
Address: O valor associado a esta chave contém o endereço detectado no documento.
Adicionalmente, são adicionadas chaves do próprio objeto results para facilitar sua busca:
DocumentCaptured: Valor do modelo de documento que foi capturado conforme o .xml de modelos. Corresponde à propriedade documentCaptured.
MatchingSidesScore: Valor que indica a correspondência entre as faces lidas do documento. Corresponde à propriedade matchingSidesScore.
timeoutDiagnostic
Esta propriedade retorna uma string que explica por que o tempo de espera do Widget se esgotou. Essa string pode ser usada em uma tela posterior de tempo de espera, onde o aplicativo principal pode fornecer mais informações ao usuário sobre o que aconteceu durante a captura do documento.
countryCaptured
País do documento.
documentTypeCaptured
Tipo de documento. Corresponde aos do item 5.1.10.
personalData
Conjunto reduzido de dados obtidos do usuário:
issuer
documentNumber
issueDate
expiryDate
name
surname
fullName
gender
birthDate
birthPlace
nationality
address
nfcKey
numSupport
mrz
Informações avançadas
Seletor de documentos - OPCIONAL
showDocumentSelector
Ativação da tela de seletor de documentos. Ela será exibida assim que o controlador for iniciado.
enabledCountries
Lista de países em ISO2 que aparecerão no seletor. Se o valor for nulo ou não contiver valores válidos, serão exibidos todos os disponíveis no SDK.
enabledDocumentTypes
Lista de tipos de documentos que aparecerão no seletor de tipos de documentos. Se o valor for nulo ou não contiver valores, serão exibidos todos os disponíveis no SDK.
Configuração avançada do componente
O comportamento do componente é definido por SelphIDConfigurationData.
resourcesPath
Indica o nome dos recursos em formato zip do componente. Exemplo: “resources-selphid-2-0.zip“.
Esse nome irá buscar o arquivo no caminho de assets.
wizardMode
Indica se o Widget fica configurado para realizar a captura de ambas as partes (frontal e traseira) do documento uma após a outra. Nesse modo, o Widget só seria iniciado uma vez e, ao terminar de capturar a frente, continuaria em seguida com o verso.
showResultAfterCapture
Indica se exibir ou não uma tela com a imagem capturada do documento após o processo de análise. Nessa tela, dá-se ao usuário a possibilidade de repetir o processo de captura se a imagem obtida do documento não estiver correta.
showTutorial
Indica se o Widget ativa a tela de tutorial. Nessa visualização, é explicado de forma intuitiva como a captura é realizada.
tutorialOnly
Indica se o Widget deve ser iniciado apenas para exibir o tutorial.
scanMode
Indica o modo de escaneamento OCR dos documentos. Dependendo da escolha, serão escaneados e buscados vários tipos de documentos ou um em específico. Esse modo pode ser de três tipos:
SelphIDScanMode.MODE_GENERIC: O modo genérico que permite escanear qualquer tipo de documento independente do país ou do tipo de documento. O resultado desse modo não é tão preciso quanto os seguintes, mas permite escanear vários documentos padrão.
SelphIDScanMode.MODE_SEARCH: O modo de busca permitirá utilizar uma whitelist e uma blacklist e buscará nos documentos que atendam a essas condições. Essas condições são indicadas na variável "specificData". Desse modo, é possível realizar a busca restringindo o número de modelos e tornando a busca muito mais precisa do que no caso genérico.
SelphIDScanMode.MODE_SPECIFIC: Busca de um documento específico. Essas condições são indicadas na propriedade "specificData" mostrada a seguir.
specificData
Esta propriedade permite definir quais documentos serão escaneados durante o processo, caso o modo de escaneamento (scanMode) seja definido como MODE_SEARCH ou MODE_SPECIFIC.
Um exemplo de configuração que permita escanear todos os documentos de nacionalidade espanhola seria o seguinte:
fullscreen
Indica se a visualização terá prioridade para ser exibida em tela cheia, se o sistema permitir.
tokenImageQuality
Indica a quantidade de qualidade que se deseja receber nas imagens tokenizadas. Valor entre 0 e 1.
documentType
Os valores permitidos são os seguintes:
SelphIDDocumentType.ID_CARD: O Widget fica configurado para realizar a captura de documentos de identidade.
SelphIDDocumentType.PASSPORT: O Widget fica configurado para realizar a captura de passaportes.
SelphIDDocumentType.DRIVERS_LICENSE: O Widget fica configurado para realizar a captura de carteiras de motorista.
SelphIDDocumentType.FOREIGN_CARD: O Widget fica configurado para realizar a captura de documentos estrangeiros.
SelphIDDocumentType.CUSTOM: O Widget fica configurado para realizar a captura de outro tipo de documentos que não correspondem a nenhuma das categorias anteriores.
WidgetSelphIDDocumentType.VISA: O Widget fica configurado para realizar a captura do visto de um país. (SDK min 2.1.2)
documentSide
Os valores permitidos são os seguintes:
SelphIDDocumentSide.FRONT: O Widget fica configurado para realizar a captura da parte frontal do documento.
SelphIDDocumentSide.BACK: O Widget fica configurado para realizar a captura da parte traseira do documento.
Timeout
É um enumerado que define o Timeout da captura de um lado do documento. Tem 3 valores possíveis:
SelphIDTimeout.SHORT: 15 segundos.
SelphIDTimeout.MEDIUM: 20 segundos.
SelphIDTimeout.LONG: 25 segundos.
SelphIDTimeout.VERY_LONG: 60 segundos.
videoFilename
Estabelece o caminho absoluto do nome do arquivo no qual será gravado um vídeo do processo de captura. O aplicativo é responsável por solicitar as permissões necessárias ao dispositivo caso esse caminho exija permissões adicionais. O Widget, por padrão, não realizará nenhum processo de gravação a menos que um caminho de arquivo seja especificado por meio deste método.
DocumentModels
Esta propriedade permite, por meio de uma string em formato xml, configurar a modelagem dos documentos que o Widget tentará capturar. A definição dessa modelagem encontra-se, por padrão, em um .xml de modelos localizado no .zip de recursos. Com essa propriedade, uma aplicação pode atualizar, em tempo real, as modelagens dos documentos.
Nota: Esta propriedade não altera o conteúdo do arquivo de recursos.
generateRawImages
Esta propriedade configura o Widget para retornar a imagem completa da câmera que foi usada para capturar o documento. Essas imagens são retornadas nas propriedades rawFrontDocument e rawBackDocument do objeto results respectivamente.
tokenPreviousCaptureData
Quando a captura do documento é realizada em 2 chamadas, esta propriedade permite passar um dicionário com as informações da captura anterior. Dessa maneira, o Widget pode combinar os resultados de ambas as leituras de forma inteligente e, assim, retornar as informações combinadas de ambas as capturas. Também permite ao Widget calcular um grau de similaridade dos dados de ambos os lados.
No caso de a captura de ambas as faces do documento ser realizada em uma única chamada, isso não é necessário, pois o Widget internamente faz esse processo.
translationsContent
Esta propriedade avançada permite, por meio de uma string em formato xml, configurar a tradução dos literais exibidos durante o processo.
Nota: Esta propriedade não altera o conteúdo do arquivo de recursos.
viewsContent
Essa propriedade avançada permite, por meio de uma string em formato xml, configurar as visualizações do Widget.
Nota: Esta propriedade não altera o conteúdo do arquivo de recursos.
showDiagnostic
Mostrar telas de diagnóstico ao final do processo
showPreviousTip
Mostra uma tela antes do início da captura com informações sobre o processo a ser realizado e um botão para iniciá-lo.
vibrationEnabled
Indica se se deseja um feedback de vibração ao final do processo.
Personalização do componente
Além da Personalização do SDK este componente permite modificar sua interface.
Textos
Os textos podem ser personalizados sobrescrevendo os valores em um arquivo XML de strings incluído no aplicativo cliente.
Exemplos de chaves disponíveis:
Diagnóstico
selphid_component_timeout_title
Tempo esgotado
selphid_component_timeout_desc
Verifique se o documento está dentro da moldura e os dados estão visíveis.
selphid_component_timeout_front_desc
Verifique se a frente do documento está dentro da moldura e os dados estão visíveis.
selphid_component_timeout_back_desc
Verifique se o verso do documento está dentro da moldura e os dados estão visíveis.
selphid_component_internal_error_title
Houve um problema técnico
selphid_component_internal_error_desc
Pedimos desculpas. Não foi possível fazer a captura
Dica prévia
selphid_component_tip_message
Enquadre seu documento dentro da moldura. A foto será tirada automaticamente.
selphid_component_tip_message_alt
Enquadre seu documento dentro da moldura. A foto será tirada automaticamente.
selphid_component_tip_anim_id_alt
Coloque seu documento de identidade na horizontal e aponte seu celular na vertical.
selphid_component_tip_anim_passport_alt
Coloque seu Passaporte na horizontal e aponte seu celular na vertical.
selphid_component_tip_anim_driving_alt
Coloque sua Licença de conduzir na horizontal e aponte seu celular na vertical.
selphid_component_tip_title
Foto do documento
selphid_component_tip_button
COMEÇAR
selphid_component_tip_button_alt
Iniciar captura de documento
selphid_component_tip_close_button_alt
VOLTAR
selphid_component_tip_info_button_alt
Ver dicas
Tutorial
selphid_component_tutorial_message_1
Busque um fundo com bom contraste.
selphid_component_tutorial_message_2
Coloque o documento dentro da moldura.
selphid_component_tutorial_message_3
Evite brilhos que dificultem a leitura do documento.
selphid_component_tutorial_1_anim_id_alt
Coloque o documento sobre uma superfície com uma cor diferente da do documento.
selphid_component_tutorial_2_anim_id_alt
Coloque seu documento de identidade na horizontal e aponte seu celular na vertical.
selphid_component_tutorial_3_anim_id_alt
Aparecem reflexos sobre o documento.
selphid_component_tutorial_1_anim_pass_alt
Coloque o Passaporte sobre uma superfície com uma cor diferente da do documento.
selphid_component_tutorial_2_anim_pass_alt
Coloque seu Passaporte na horizontal e aponte seu celular na vertical.
selphid_component_tutorial_3_anim_pass_alt
Aparecem reflexos sobre o documento.
selphid_component_tutorial_1_anim_driving_alt
Coloque o documento sobre uma superfície com uma cor diferente da do documento.
selphid_component_tutorial_2_anim_driving_alt
Coloque seu documento de identidade na horizontal e aponte seu celular na vertical.
selphid_component_tutorial_3_anim_driving_alt
Aparecem reflexos sobre o documento.
selphid_component_tip_health_alt
Coloque seu cartão de saúde na horizontal e aponte seu celular na vertical.
selphid_component_tutorial_1_anim_health_alt
Coloque o cartão de saúde sobre uma superfície com uma cor diferente da do documento.
selphid_component_tutorial_2_anim_health_alt
Coloque seu documento de identidade na horizontal e aponte seu celular na vertical.
selphid_component_tutorial_3_anim_health_alt
Aparecem reflexos sobre o documento.
selphid_component_tip_custom_alt
--
selphid_component_tutorial_1_anim_custom_alt
--
selphid_component_tutorial_2_anim_custom_alt
--
selphid_component_tutorial_3_anim_custom_alt
--
selphid_component_tutorial_close_button_alt
Voltar ao tutorial anterior
Seletor de Documento e País
selphid_selector_title
Realize seu Onboarding
selphid_selector_country_label
De que país é o seu documento?
selphid_selector_country_placeholder
Selecione um país
selphid_selector_country_search_label
Escolha um país
selphid_selector_country_search_placeholder
Busque um país
selphid_selector_country_search_clear
Limpar busca
selphid_selector_country_no_results
Sem resultados
selphid_selector_document_label
Qual documento você usará?
selphid_selector_document_placeholder
Selecione um documento
selphid_selector_document_dialog_title
Escolha o documento
selphid_selector_document_dialog_cancel
CANCELAR
selphid_selector_document_dialog_select
SELECIONAR
selphid_selector_continue
Continuar
selphid_selector_type_id_card
Documento de identidade
selphid_selector_type_passport
Passaporte
selphid_selector_type_drivers_license
Licença de conduzir
selphid_selector_type_foreign_card
Cartão de residência
selphid_selector_type_credit_card
Cartão de crédito
selphid_selector_type_custom
Personalizado
selphid_selector_type_visa
Visto
Animações
O componente utiliza animações Lottie (.json) tanto na dica prévia quanto nos tutoriais.
Se desejar modificar as animações do SDK, deverão ser incluídos os arquivos com o mesmo nome na pasta res/raw/
Atualizado