Guia de referência da API

1. Introdução

Este documento inclui a descrição da API das bibliotecas fornecidas no produto FacePhi SelphID SDK.

2. Descrição da API de SelphID (Front-end)

SelphID SDK é um conjunto de bibliotecas de servidor que utiliza as informações geradas pelos Widgets de FacePhi para aplicações nativas ou web. Como descrito nas seções a seguir, são fornecidos alguns componentes denominados Widgets para a captura facial (Selphi) e a captura de documentos de identidade (SelphID), que podem ser integrados no front-end de qualquer aplicação.

2.1. Widget Selphi

Por meio do widget Selphi, que incorpora o mecanismo de detecção e extração facial e de prova de vida do usuário, é possível obter as seguintes informações por meio das propriedades indicadas a seguir:

• Image propriedade: Representa a imagem do usuário com a pose facial mais frontal detectada.

• TemplateRaw propriedade: Representa o template biométrico tokenizado do usuário com a pose facial mais frontal detectada. Este template é utilizado para realizar a autenticação biométrica com o SelphID SDK.

Nota

Adicionalmente, é fornecida uma funcionalidade de tokenização generateTemplateRaw (ver API) que permite converter uma imagem ou um buffer de dados em um buffer de dados tokenizado na forma de templateRaw. Este templateRaw pode ser utilizado em várias funcionalidades do SelphID SDK.

2.2. Widget SelphID

Por meio do widget SelphID, que incorpora o mecanismo automático de detecção e captura de documentos, é possível obter as seguintes informações por meio das propriedades indicadas a seguir:

• TokenOCR propriedade: Representa um Token (marca de tempo + criptografia AES256) que contém os dados detectados no documento por meio do OCR realizado.

• TokenFrontDocument propriedade: Representa a imagem tokenizada (marca de tempo + criptografia AES256) da frente do documento ajustada às bordas do documento.

• TokenBackDocument propriedade: Representa a imagem tokenizada (marca de tempo + criptografia AES256) do verso do documento ajustada às bordas do documento.

• TokenFaceImage propriedade: Representa a imagem tokenizada (marca de tempo + criptografia AES256) da fotografia do usuário no documento. Este Token é utilizado para realizar a autenticação biométrica com o SDK.

• TokenRawFrontDocument propriedade: Representa a imagem tokenizada (marca de tempo + criptografia AES256) da frente do documento sem ser recortada às bordas do documento, ou seja, exatamente como foi capturada pela câmera.

• TokenRawBackDocument propriedade: Representa a imagem tokenizada (marca de tempo + criptografia AES256) do verso do documento sem ser recortada às bordas do documento, ou seja, exatamente como foi capturada pela câmera.

3. Descrição da API de SelphID (Back-end)

A seguir, é descrita a API das bibliotecas fornecidas em SelphID, detalhando os métodos que o integrador pode usar para incorporar as funcionalidades de reconhecimento facial, extração de informações em documentos de identidade e validação de documentos.

3.1. Inicialização das bibliotecas

SelphIDVerifier representa a classe principal das bibliotecas, que contém todos os métodos disponíveis para cada uma das funcionalidades.

A inicialização das bibliotecas pode ser realizada de três formas diferentes, dependendo das variáveis de ambiente configuradas:

3.1.1. Inicialização por meio do método loadWithConfigPath()

Passos prévios

Configure as variáveis de ambiente e o arquivo config.cfg (configuração do SDK para instalação On-premise):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Specifies the path where the configuration file is located.
  String configurationFilePath =
    "C:/Program Files/FacePhi/Sdk/SelphId/x.x.x.x/config/config.cfg";

  // Load the library indicating the path where to look for the config file.
  verifier.loadWithConfigPath(configurationFilePath);

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

3.1.2. Inicialização por meio do método load()

Passos prévios

Configure as variáveis de ambiente e o arquivo config.cfg (configuração do SDK para instalação On-premise):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

Não é necessário especificar o caminho do arquivo de configuração, pois ele será procurado automaticamente no seguinte caminho: FACEPHI_SELPHID_INSTALL_PATH/config/selphid.cfg

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.load();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

3.1.3. Inicialização por meio do método loadFromEnvVars()

Passos prévios

Configure as variáveis de ambiente (configuração do SDK para instalação On-premise):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

• FACEPHI_SELPHID_DEBUGPATH_KEY

• FACEPHI_SELPHID_USAGEPATH_KEY

• FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY

• FACEPHI_SELPHID_FACIAL_LICPATH_KEY

Em vez de configurar o arquivo config.cfg, essas variáveis são definidas diretamente como variáveis de ambiente.

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.loadFromEnvVars();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

Importante

A inicialização das bibliotecas por meio do método load(), loadWithConfigPath() ou loadFromEnvVars() deve ser realizada apenas uma vez durante o ciclo de vida da sua aplicação.

Depois de finalizados todos os processos que envolvem o uso dessas bibliotecas, é importante liberar os recursos associados a elas; não se esqueça de descarregar (unload) a biblioteca antes de fechar a aplicação.

O encerramento das bibliotecas por meio do método unload() deve ser realizada apenas uma vez durante o ciclo de vida da sua aplicação. Uma vez invocado o método unload(), já não é possível realizar um load().

Se ocorrer alguma condição que impeça o carregamento correto das bibliotecas, será lançada uma SelphIDException. Para conhecer os tipos de exceção, consulte a seção correspondente 3.10. Descrição de SelphIDException na API fornecida.

3.2. Métodos de extração facial

Para realizar a extração dos dados faciais de um usuário, o integrador dispõe de diferentes métodos na classe SelphIDVerifier. O integrador deverá utilizar um método ou outro dependendo dos dados gerados no cliente. A seguir, são descritas cada uma das possíveis situações.

Nota

O resultado desses métodos será sempre um objeto SelphIDFacialExtractionResult, explicado em 3.9.1. SelphIDFacialExtractionResult.

3.2.1. Extração facial por meio de uma imagem

O método a ser utilizado é o seguinte:

SelphIDFacialExtractionResult r = extractFacialWithImageBuffer(
  byte[] imageBuffer,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma extração facial por meio de uma imagem são os seguintes (método de exemplo):

Passos prévios

• Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.

• Envie a string em base64 da imagem ao servidor.

String extractBiometricFacialTemplate(String imageBase64) {
  // Decode base64 to get the byte array corresponding to the image on the server.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithImageBuffer(imageBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}

3.2.2. Extração facial por meio de um template biométrico

O método a ser utilizado é o seguinte:

SelphIDFacialExtractionResult r = extractFacialWithRawTemplate(
  byte[] rawTemplateBuffer,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma extração facial por meio de uma template biométrica são os seguintes (método de exemplo):

Passos prévios

• Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.

• Envie a string em base64 do template biométrico ao servidor.

String extractBiometricFacialTemplate(String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to the template.
  byte[] rawTemplateBuffer = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithRawTemplate(rawTemplateBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}

3.3. Métodos de autenticação facial

Para realizar a autenticação facial de um usuário, o integrador dispõe de diferentes métodos na classe SelphIDVerifier. O integrador deverá utilizar um método ou outro dependendo dos dados gerados no cliente. Cada uma das possíveis situações é descrita nos subtópicos a seguir.

Nota

O resultado desses métodos será sempre um objeto SelphIDFacialAuthenticationResult, explicado em 3.9.2. SelphIDFacialAuthenticationResult.

3.3.1. Autenticação facial por meio de imagens

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageBuffers(
  byte[] imageQuery,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

Passos prévios

• Obtenha a primeira imagem (string em base64) por meio da propriedade Image usando o widget Selphi.

• Obtenha a segunda imagem (string em base64) por meio da propriedade Image usando o widget Selphi.

• Envie ambas as strings em base64 ao servidor.

boolean isMatch(String firstImageBase64, String secondImageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageBuffers(
    imageQuery, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.2. Autenticação facial por meio de templates biométricos

O método a ser utilizado é o seguinte:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma autenticação facial por meio de dois templates biométricos são os seguintes (método de exemplo):

Passos prévios

• Obtenha o primeiro template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.

• Obtenha o segundo template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.

• Envie ambas as strings em base64 ao servidor.

boolean isMatch(String firstTemplateRawBase64, String secondTemplateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] templateQuery = Base64.getDecoder().decode(
    firstTemplateRawBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    secondTemplateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawTemplates(
    templateQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.3. Autenticação facial por meio de uma imagem e um template biométrico

O método a ser utilizado é o seguinte:

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma autenticação facial por meio de uma imagem e um template biométrico são os seguintes (método de exemplo):

Passos prévios

• Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.

• Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.

• Envie ambas as strings em base64 ao servidor.

boolean isMatch(String imageBase64, String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    imageBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageRawTemplate(
    imageQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.4. Autenticação facial por meio da fotografia do documento e uma imagem

O método a ser utilizado é o seguinte:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocument,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);

Os passos necessários para realizar uma autenticação facial por meio da fotografia do documento e uma imagem são os seguintes (método de exemplo):

Passos prévios

• Obtenha o Token da fotografia do documento (string em base64) por meio da propriedade TokenFaceImage usando o widget SelphID.

• Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.

• Envie ambas as strings em base64 ao servidor.

boolean isMatch(String tokenFaceImageBase64, String imageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentImage(
    rawDocument, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.5. Autenticação facial por meio da fotografia do documento e um template biométrico

O método a ser utilizado é o seguinte:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocument,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

• Os passos necessários para realizar a autenticação facial por meio da fotografia do documento e do template biométrico do usuário são os seguintes (método de exemplo):

Passos prévios

• Obtenha o Token da fotografia do documento (string em base64) por meio da propriedade TokenFaceImage usando o widget SelphID.

• Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.

• Envie ambas as strings em base64 ao servidor.

boolean isMatch(String rawDocumentBase64, String templateTargetBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    rawDocumentBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateTargetBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentRawTemplate(
    rawDocument, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.4. Método de extração de dados do documento

Para obter os dados do documento necessários nos processos de onboarding digital, o integrador dispõe de um método na classe SelphIDVerifier.

Nota

O resultado deste método será um objeto SelphIDDocumentResult que contém todos os dados detectados no documento. Para mais informações, consulte a seção 3.9.3. SelphIDDocumentResult.

3.4.1. Obtenção dos dados detectados em um documento

O método a ser utilizado é o seguinte:

SelphIDDocumentResult extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  SelphIDVerifierOptions selphIDVerifierOptions
);

Os passos necessários para obter os dados de um documento são os seguintes (método de exemplo):

Passos prévios

• Obtenha o valor da propriedade TokenOCR (string em base64) usando o widget SelphID.

• Envie a string em base64 ao servidor.

void printDocumentData(String tokenOCRBase64) {
  // Decode base64 to obtain the byte array corresponding to the token on the server.
  byte[] rawDocumentBuffer = Base64.getDecoder().decode(
    tokenOCRBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDDocumentResult r = verifier.extractDocumentWithRawDocument(
    rawDocumentBuffer, options);

  // Explore the information obtained in SelphIDDocumentResult.

  // Get document keys.
  String[] keys = r.listDocumentKeys();

  // Print document data.
  for(int x=0; x<keys.length; x++) {
    System.out.println(
      keys[x] + ": " + getDocumentValue(keys[x]);
    );
  }
}

3.5. Métodos de avaliação de prova de vida

Para avaliar a prova de vida do usuário no servidor, funcionalidade necessária no processo de onboarding digital para evitar fraude por foto ou vídeo, o integrador dispõe de um método para esse fim na classe SelphIDVerifier.

Nota

O resultado desses métodos será sempre um objeto SelphIDFacialLivenessResult, explicado em 3.9.4. SelphIDFacialAuthenticationResult.

3.5.1. Avaliação de prova de vida a partir de uma imagem

SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer
);

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

Passos prévios

• Obtenha uma imagem do usuário (string em base64) usando o widget Selphi.

• Envie a string em base64 da imagem ao servidor.

boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenesWithImageBuffer(
    imageBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}

3.5.2. Avaliação de prova de vida a partir de uma imagem tokenizada

A partir da versão 6.21.0, a imagem tokenizada incorpora um mecanismo de defesa contra ataques de injeção. Se for detectado um token inválido, será retornado NoneBecauseTokenDataError ou NoneBecauseTokenSecurity como diagnóstico.

SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer
);

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

Passos prévios

• Obtenha uma imagem do usuário (string em base64) usando o widget Selphi.

• Envie a string em base64 da imagem ao servidor.

boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] tokenBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenessWithTokenBuffer(
    tokenBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}

3.6. Métodos de identificação 1:N

Para realizar buscas 1:N que permitam identificar um determinado padrão biométrico frente a um banco de dados e, assim, obter um conjunto de candidatos com um maior percentual de semelhança, o integrador dispõe de diferentes métodos na classe SelphIDIdentifier.

public class SelphIDIdentifier {
  // True if gallery has been created correctly.
  boolean createGallery(String galleryID) {}

  // True if gallery has been created correctly.
  boolean createGalleryWithPath(String galleryID, String galleryFilePath) {}

  // True if gallery has been removed correctly.
  boolean clearGallery(String galleryID) {}

  // Get all galleries for identification.
  String[] getAllGalleries() {}

  // True if each gallery have been removed correctly.
  boolean clearAllGalleries() {}

  // Feed a gallery with a new template using SelphIDFacialExtractionResult
  int enrollWithExtractionResult(String galleryID, String templateID, SelphIDFacialExtractionResult extractionResult) {}

  // Feed a gallery with a new template using byte[] template
  int enrollWithFacialTemplate(String galleryID, String templateID, byte[] facialTemplateBuffer) {}

  // Check if a person exists in the gallery via SelphIDFacialExtractionResult.
  SelphIDIdentifierResult identifyWithExtractionResult(String galleryID, SelphIDFacialExtractionResult extractionResult, SelphIDIdentifierOptions identifierOptions) {}

  // Check if a person exists in the gallery via byte[] template.
  SelphIDIdentifierResult identifyWithFacialTemplate(String galleryID, byte[] facialTemplateBuffer, SelphIDIdentifierOptions identifierOptions) {}

  SelphIDFacialGalleryInfo getGalleryInfo(String galleryID) {}

  boolean removeWithGalleryIndex(String galleryID, int templateIndex) {}

  boolean removeWithTemplateID(String galleryID, String templateID) {}
}

3.6.1. Construção da galeria de busca

Como passo prévio para realizar operações de identificação, deve-se criar uma galeria e registrar nela o conjunto de padrões biométricos sobre os quais a busca será realizada. Para incorporar templates à galeria, você pode usar os seguintes métodos:

public class SelphIDIdentifier {
  int enrollWithExtractionResult(
    String galleryID,
    String templateID,
    SelphIDFacialExtractionResult extractionResult
  ) {}

  int enrollWithFacialTemplate(
    String galleryID,
    String templateID,
    byte[] facialTemplateBuffer
  ) {}
}

Em ambos os métodos, será especificado o identificador da galeria à qual o template deve ser adicionado, bem como um identificador lógico relacionado à lógica de negócios da aplicação, de modo que os candidatos obtidos como resultado de uma busca na galeria possam ser vinculados a ele.

// 1. Create the gallery.
String galleryID = "my-new-id-or-uuid-1";
createGallery(galleryID);

// 2. Generate the facial templates from the images if you do not have them.
byte[] image1 = ...;
byte[] image2 = ...;
SelphIDVerifierOptions options = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult1 = extractFacialWithImageBuffer(
  image1, options);

SelphIDFacialExtractionResult extractionResult2 = extractFacialWithImageBuffer(
  image2, options);

// 3. The obtained facial templates will be added to the gallery by using any of the following methods of the `SelphIDIdentifier` class (you need to initializate it).

//    3.1. Create / Generate the template ID that will have in gallery
String templateID1 = "my-new-id-or-uuid-2";
String templateID2 = "my-new-id-or-uuid-3";

//    3.2. Insert the templates into the gallery with enrollWithExtractionResult
identifier.enrollWithExtractionResult(galleryID, templateID1, extractionResult1);

//    3.3. Insert the templates into the gallery with enrollWithFacialTemplate
byte[] facialTemplateBuffer = extractionResult2.getFacialTemplate();

identifier.enrollWithFacialTemplate(galleryID, templateID2, facialTemplateBuffer);

Nota

Para registrar um template biométrico em uma galeria, será necessário gerar o padrão facial equivalente ou FacialTemplate por meio de qualquer um dos seguintes métodos da classe SelphIDVerifier:

• ExtractFacialWithRawTemplate

• ExtractFacialWithImageBuffer

Consulte a seção 3.2.1. Extração facial por meio de uma imagem.

3.6.2. Identificação de um template frente a uma galeria de busca

O processo de busca será realizado por meio de qualquer um dos dois métodos a seguir da classe SelphIDIdentifier:

public class SelphIDIdentifier {
  SelphIDIdentifierResult identifyWithExtractionResult(
    String galleryID,
    SelphIDFacialExtractionResult extractionResult,
    SelphIDIdentifierOptions identifierOptions
  ) {}

  SelphIDIdentifierResult identifyWithFacialTemplate(
    String galleryID,
    byte[] facialTemplateBuffer,
    SelphIDIdentifierOptions identifierOptions
  ) {}
}

Serão especificados o identificador da galeria e um objeto SelphIDIdentifierOptions com as seguintes opções de busca:

• MaxIdentificationCandidates, para indicar o número máximo de candidatos retornados, ordenados do maior para o menor percentual de similaridade.

• MinIdentificationSimilarity, para indicar o limite mínimo de similaridade na comparação para que um candidato seja incluído no conjunto de resultados.

Nota

Por padrão, MaxIdentificationCandidates será 20 e MinIdentificationSimilarity será 0f.

A seguir veremos um exemplo com ambos os métodos:

// 1. Para uma galeria existente, só precisamos do seu ID e da imagem para procurar essa pessoa na galeria.
String galleryID = "galleryID";
byte[] imageToSearch = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();

// 2. Configure as SelphIDIdentifierOptions
identifierOptions.setMaxIdentificationCandidates(5);
identifierOptions.setMinIdentificationSimilarity(0.6f);

// 3. Extraia o template facial
SelphIDVerifierOptions verifierOptions = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult = identifier.extractFacialWithImageBuffer(
  imageToSearch, verifierOptions);

// 4. Pesquise-o com identifyWithExtractionResult ou identifyWithFacialTemplate se você já tiver o template facial.
SelphIDIdentifierResult result = identifier.identifyWithExtractionResult(
  galleryID, extractionResult, identifierOptions);

byte[] facialTemplateBuffer = extractionResult.getFacialTemplate();
SelphIDIdentifierResult result = identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// 5. Veja os resultados. Obtemos um array com todas as possíveis coincidências, então, por exemplo, se quisermos obter a primeira coincidência:
if (result.size() > 0) {
  FacialAuthenticationStatus authenticate = identifierResult.getFacialAuthenticationStatus(0);
  float similarity = result.getSimilarity(0);
  String templateId = result.getTemplateID(0);
}

Nota

Para saber mais sobre SelphIDIdentifierResult, consulte a seção 3.9.5. SelphIDIdentifierResult.

3.6.3. Excluir um template da galeria

O processo de exclusão consiste em bloquear um template biométrico de uma galeria específica para que ele não seja levado em conta nos processos de identificação. Se utilizarmos a variável de ambiente FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=noerase, essa exclusão não reduz o tamanho da galeria nem a indexação dos templates biométricos associados. Pelo contrário, omitir essa variável ou utilizar FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase reduzirá o tamanho da galeria após a exclusão, alterando a indexação dos templates.

public class SelphIDIdentifier {
  boolean removeWithGalleryIndex(
    String galleryID,
    int templateIndex
  ) {}

  boolean removeWithTemplateID(
    String galleryID,
    String templateID
  ) {}

}

O processo de exclusão é realizado com o seguinte método da classe SelphIDIdentifier:

// Por exemplo, vamos remover um usuário específico.
String galleryID = "galleryID";
byte[] facialTemplateBuffer = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();
identifierOptions.setMaxIdentificationCandidates(1);
identifierOptions.setMinIdentificationSimilarity(0.5f);

// Pesquise o template coincidente na galeria.
SelphIDIdentifierResult identifierResult = identifier.identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// Se a coincidência tiver sido encontrada e corresponder, ela será removida.
if (result.size() > 0 &&
  identifierResult.getFacialAuthenticationStatus(0) == FacialAuthenticationStatus.Positive) {
  // Obtenha o índice do template
  int templateIndex = identifierResult.getGalleryIndex(0);

  boolean removed = removeWithGalleryIndex(galleryID, templateIndex);

  if (removed) {
    System.out.println("Template correctly removed.");
  }
}

3.6.4. Consultar e excluir templates obsoletos

A partir da versão 6.17.0, cada padrão biométrico armazena o carimbo de data/hora (relógio do sistema) em que foi indexado na galeria. Isso permite consultar e excluir templates "expirados" de acordo com critérios específicos.

public class SelphIDIdentifier {
  String[] listObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}

  String[] removeObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}
}

Em ambos os casos, serão listados os IDs de template cujos carimbos de data/hora sejam anteriores ao intervalo indicado (em segundos). No caso de removeObsoleteGalleryTemplateIDs(), a operação será atômica e eliminará todos os padrões obsoletos em uma única operação. Se tiver sido configurado FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase, o tamanho da galeria será reduzido e os padrões restantes serão reindexados.

// Por exemplo, vamos remover um usuário específico.
String galleryID = "galleryID";

// Remova todos os padrões biométricos com mais de um dia
String [] obsoleteIDs = removeObsoleteGalleryTemplateIDs(galleryID, 24 * 3600);

if (obsoleteIDs.length > 0) {
  System.out.println("Biometric patterns removed from gallery.");
  for (int i = 0; i < obsoleteIDs.length; ++i)
    System.out.println(obsoleteIDs[i]);
}

3.6.5. Consultar informações de uma galeria

O objetivo do processo de consulta de uma galeria é servir como etapa prévia para poder realizar outras consultas sobre ela.

O processo será realizado com a seguinte classe de SelphIDIdentifier:

public class SelphIDIdentifier {
  SelphIDFacialGalleryInfo getGalleryInfo(
    String galleryID
  ) {}
}

Deve ser utilizado um identificador de galeria para consultar a galeria específica. A seguir veremos em que consiste o objeto SelphIDFacialGalleryInfo:

public class SelphIDFacialGalleryInfo {
  // Verifica se a galeria é válida.
  boolean getValidGallery();

  // Obtém o ID da galeria.
  String getGalleryID();

  // Obtém o tamanho da galeria.
  int getGallerySize();

  // Obtém um template com o índice.
  String getTemplateID(int index);

  // Obtém todos os índices de uma galeria que correspondem a um valor exato.
  int[] getIndicesWithTemplateID(String templateID);
}

3.6.6. Consultar os índices que coincidem com um templateID específico

O processo de consulta de todos os índices de uma galeria que coincidem com um valor exato de templateID deve ser realizado com o seguinte método de SelphIDFacialGalleryInfo que vimos na seção anterior:

Importante

A partir do SelphID 6.15.0, não são permitidos elementos com templateID duplicado.

public class SelphIDFacialGalleryInfo {
  int[] getIndicesWithTemplateID(
    String templateID
  );
}

Deve ser especificado um templateID que corresponda ao templateID que se busca na galeria.

Para isso, é necessário dispor de uma instância de SelphIDFacialGalleryInfo com dados válidos:

String galleryID = "galleryID";
String templateID = "templateID";

SelphIDFacialGalleryInfo galleryInfo = identifier.getGalleryInfo(galleryID);

int[] indicesTemplateID = galleryInfo.getIndicesWithTemplateID(templateID);

3.7. Orquestrador

O orquestrador permite obter, na mesma chamada, a autenticação facial e o teste de vida da pessoa. Podemos optar por realizar o teste com uma imagem e um template, ou com dois templates.

Importante

O teste de vida será realizado somente após uma autenticação bem-sucedida.

SelphIDVerifierResult r = verifySelphIDWithImageRawTemplate(
  byte[] imageBuffer,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

SelphIDVerifierResult r = verifySelphIDWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

Nota

Para mais informações sobre SelphIDVerifierResult, consulte a seção 3.9.6. SelphIDVerifierResult.

3.8. API Tracking

A partir da versão 4.1.0, o SelphID-SDK incorpora a funcionalidade de rastreamento de eventos (event tracking) que permite monitorar e visualizar a atividade da API por meio de uma interface web. A licença do SelphID incluirá todos os dados necessários para acessar a plataforma (na versão single-tenant).

Todos os métodos anteriores de outras versões da API continuam vigentes. Foram adicionados alguns métodos duplicados que agora recebem um novo parâmetro no qual se encontram dados tokenizados com a informação essencial para se comunicar com o servidor de Tracking. Esse parâmetro se denomina extraData.

3.8.1. Versão Multi-tenant

A partir da versão 4.3.0, o SelphID-SDK permite dois modos de funcionamento em relação ao registro de eventos por meio da API-Tracking:

• Single-tenant: Os dados de conexão ao serviço de API Tracking estão criptografados dentro da licença do SelphID-SDK e serão utilizados em todas as chamadas ao serviço.

• Multi-tenant: Os dados de conexão serão recebidos em cada chamada por meio do aplicativo móvel. Isso permitirá que o SDK registre eventos em diferentes servidores de acordo com o cliente que realiza a chamada.

Importante

Para habilitar o modo multi-tenant, os dados de Tracking não devem ser incluídos na licença do SelphID-SDK. Caso contrário, o modo single-tenant será ativado ao iniciar o backend.

A partir da versão 5.0.0, é possível alternar entre os modos Single-tenant e Multi-tenant em tempo de execução, utilizando estes métodos de SelphIDVerifier:

void setMultitenantMode(boolean multiTenant);

boolean isMultitenantEnabled();

3.8.2. Registro

Com o seguinte método, permite-se a descriptografia dos dados tokenizados em rawDocumentBuffer, como: OCR, imagens do documento etc. No parâmetro extraData devem ser enviados os dados necessários para o serviço de Tracking.

SelphIDDocumentResult r = extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  byte[] extraData,
  SelphIDVerifierOptions options
);

Os métodos a seguir recebem uma imagem criptografada rawTemplateBufferTarget ou uma imagem não criptografada imageBufferTarget, para compará-la com a imagem extraída do documento rawDocumentBufferQuery. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro extraData.

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocumentBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocumentBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

3.8.3. SelphIDVerifierOptions

Os métodos a seguir, adicionados à classe SelphIDVerifierOptions, permitem que as informações inseridas pelo cliente sejam representadas nos servidores de Tracking, no caso de uso de registro.

public class SelphIDVerifierOptions {
  void setElapsedTimeAllowed(int elapsedTimeAllowed);
  void setFutureTimeAllowed(int futureTimeAllowed);
  void setFacialDetectionType(FacialDetectionType facialDetectionType);
  void setMinFaceAbs(int minFaceAbs);
  void setMinFaceRel(float minFaceRel);
  void setFalseDetectRate(float rate);
  void setMinIODThreshold(int minIODThreshold);
  void setMaxPoseThreshold(int maxPoseThreshold);
  void setMinimumFacialQuality(int minimumFacialQuality);
  void setAnalyticsDetection(boolean analyticsDetection);
  void setFacialTemplateRawExtraction(boolean facialTemplateRawExtraction);
  void setOptionalDataClientInformation(String json);
  void setCustomFacialAuthenticationThreshold(int customFacialAuthenticationThreshold);
  void setLivenessDepth(LivenessDepth livenessDepth);
}

O parâmetro de entrada do método setOptionalDataClientInformation deve ser um JSON bem formado que aceitará as seguintes chaves:

{
  "address": "String",
  "birthDate": "String",
  "birthPlace": "String",
  "city": "String",
  "documentNumber": "String",
  "name": "String",
  "nationality": "String",
  "surname": "String"
}

Nota

Qualquer outra chave será ignorada. No futuro, haverá suporte a mais chaves.

A partir da versão 6.17.0, foi adicionada a propriedade futureTimeAllowed. Isso permite estabelecer um intervalo de tempo (em segundos) durante o qual serão aceitos templates e imagens tokenizadas com uma data futura, retornando true no método getValidTimeStamp(). Isso tem como objetivo mitigar as diferenças de fuso horário entre dispositivos. Esse valor pode ser configurado globalmente por meio da variável de ambiente FACEPHI_SELPHID_FUTURE_TIME_ALLOWED=3600.

A partir da versão 6.18.0, podemos especificar quais pipelines de Liveness queremos executar para cada operação por meio de setLivenessDepth(). No caso de None (valor padrão), será aplicada a configuração global definida por FACEPHI_SELPHID_FACIALLIVENESS_DEPTH.

3.8.4. Autenticação

Os métodos a seguir estão disponíveis para realizar a autenticação. Os parâmetros rawTemplateBuffer recebem a imagem criptografada, e o parâmetro imagebufferQuery recebe a imagem não criptografada. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro extraData.

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] rawTemplateBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

3.8.5. Liveness passivo

Os métodos a seguir estão disponíveis para realizar o teste de vida passivo. O parâmetro tokenBuffer recebe a imagem criptografada e imageBuffer a imagem não criptografada. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro extraData.

SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer,
  byte[] extraData
);

SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer,
  byte[] extraData
);

3.8.6. Eventos personalizados

A partir da versão 4.5.0, o SelphID implementa a possibilidade de enviar eventos personalizados para a API de Tracking, não vinculados a nenhuma operação interna do SDK. Todas as operações de eventos personalizados retornam um código de status e uma mensagem, dentro de um objeto SelphIDApiTrackingResult.

O método a seguir permite enviar à API de Tracking o evento de Autenticação facial, utilizando os parâmetros authStatus e similarity. Também podemos registrar no serviço de API Tracking a(s) imagem(ns) envolvida(s) na autenticação. Ambas as imagens são opcionais, aceitando buffers nulos ou vazios.

SelphIDApiTrackingResult r = authenticateFacialTrackingEvent(
  TrackingFamily family,
  FacialAuthenticationStatus authStatus,
  float similarity,
  String source,
  byte[] imageBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData
);

Valores possíveis de TrackingFamily:

public enum TrackingFamily {
  Onboarding,
  Authentication
}

O método a seguir permite enviar à API de Tracking o evento de Liveness, utilizando os parâmetros diagnostic e similarity. Também podemos registrar no serviço de API Tracking a imagem envolvida no processo de vida, embora isso seja opcional, aceitando um buffer nulo ou vazio.

SelphIDApiTrackingResult r = evaluatePassiveLivenessTrackingEvent(
  TrackingFamily family,
  FacialLivenessDiagnostic diagnostic,
  String source,
  byte[] imageBuffer,
  byte[] extraData
);

O método a seguir permite enviar à API de Tracking o evento de Autenticação por voz, utilizando o parâmetro probability. Também podemos registrar no serviço de API Tracking as pistas de áudio envolvidas no processo de autenticação por voz. Ambos os buffers são opcionais, aceitando valores nulos ou vazios.

SelphIDApiTrackingResult r = voiceAuthenticationTrackingEvent(
  float probabiliy,
  String source,
  byte[] audioDataBufferQuery,
  byte[] audioDataBufferTarget,
  byte[] extraData
);

O método a seguir permite enviar um evento personalizado de OCR ao servidor da API Tracking.

SelphIDApiTrackingResult r =  ocrTrackingEvent(
  String ocrDataJson,
  String source,
  byte[] extraData
);

ocrDataJson é um dicionário chave-valor em formato JSON bem formado. Aceita qualquer tipo de nome de chave com qualquer valor de string:

{
  "OCR_Key1": "OCR_Value1",
  "OCR_Key2": "OCR_Value2",
  "OCR_Key3": "OCR_Value3",
  "OCR_Key4": "OCR_Value4",
  "OCR_Key5": "OCR_Value5"
}

O método a seguir permite enviar um evento personalizado SECURITY_INFO_DATA ao servidor da API Tracking:

  SelphIDApiTrackingResult r = securityInfoTrackingEvent(
  String securityDataJson,
  boolean succeed,
  String source,
  byte[] extraData
  );

securityDataJson são os dados de segurança em formato JSON:

{
  "Security_Key1": "Security_Value1",
  "Security_Key2": "Security_Value2",
  "Security_Key3": "Security_Value3",
  "Security_Key4": "Security_Value4",
  "Security_Key5": "Security_Value5"
}

succeed é um valor booleano que indica se a obtenção dos dados de segurança foi realizada corretamente ou não, e source é o nome do serviço ou da origem dos dados de segurança.

Para todas as operações de eventos personalizados, podemos modificar o campo criptografado eventSource dentro do token extraData.

byte[] extraData2 = setTrackingEventSource(
  String eventSource,
  byte[] extraData
);

Dentro dos eventos personalizados, oferece-se a possibilidade de encerrar a operação por meio do seguinte método:

SelphIDApiTrackingResult r = finishTrackingEvent(
  TrackingFamily family,
  OperationResultStatus status,
  OperationResultReason reason,
  byte[] extraData
);

Este método registrará no serviço de API Tracking os eventos de Resultado da operação (Operation result) e Finalização de mudança de etapa (Step change finish), que encerram a operação.

Importante

O significado desses atributos, incluindo esses enums, será determinado pelo usuário.

Valores possíveis de OperationResultStatus:

public enum OperationResultStatus {
  Succeeded,

  // Negado.
  Denied,

  // Erro.
  Error,

  // Cancelado.
  Cancelled
}

Valores possíveis de OperationResultReason:

public enum OperationResultReason {
  // Não especificamos um motivo concreto.
  None,

  // Algum erro ao usar o SDK.
  InternalError,

  // A operação foi cancelada pelo usuário.
  CancelledByUser,

  // O Timeout definido expirou.
  Timeout,

  // A validação do documento falhou.
  DocumentValidationNotPassed,

  // Erro durante a validação do documento.
  DocumentValidationError,

  // Authentication falhou.
  AuthenticationNotPassed,

  // Erro durante a Authentication.
  AuthenticationError,

  // Liveness falhou.
  LivenessNotPassed,

  // Erro durante o Liveness.
  LivenessError
}

3.8.7. Servidor proxy

Desde a Versão 4.5.5 do SelphID-SDK, é possível enviar solicitações para a API de Tracking por meio de um servidor proxy. Para configurar os parâmetros do proxy, use o seguinte método:

setTrackingProxy(
        String proxyHost,
        int proxyPort,
        String proxyUser,
        String proxyPass);

Para desabilitar o proxy, deve ser passada uma string vazia como parâmetro proxyHost.

3.9. Descrição dos resultados da API

As seguintes propriedades, nas classes de resultado, permitem avaliar os resultados de cada um dos métodos mencionados acima.

A partir da versão 6.18.0, além de verificar a validade de um Token por meio de getValidTimeStamp(), agora podemos obter a marca temporal incorporada no próprio Token por meio de getTokenTimeStamp(). Isso afeta:

• SelphIDFacialExtractionResult.

• SelphIDFacialAuthenticationResult.

• SelphIDDocumentResult.

• SelphIDFacialLivenessResult.

3.9.1. SelphIDFacialExtractionResult

Apresenta diferentes propriedades para avaliar o resultado da extração facial:

public class SelphIDFacialExtractionResult {
  // Indica se a extração conseguiu ser processada com sucesso.
  boolean getExtractionOK() {}

  // Padrão biométrico da pessoa detectada.
  byte[] getFacialTemplate() {}

  // Valor (0, 1) que indica o grau de confiabilidade da extração.
  float getFaceConfidence() {}

  // Localização dos pontos de referência detectados na imagem.
  Point getLeftEye() {}
  Point getRightEye() {}
  Point getChin() {}
  Point getNose() {}
  Point getLeftMouth() {}
  Point getRigthMouth() {}

  // Distância interocular.
  int getIOD() {}

  // Orientação do rosto em relação à câmera. Os valores possíveis são os seguintes:
  FacialPose getFacialPose() {}

  // Ângulos de orientação do rosto.
  float getYaw() {}
  float getPitch() {}
  float getRoll() {}

  // Valor (0, 1) que indica a qualidade da imagem de entrada.
  float getImageQuality() {}

  // Indica a qualidade do rosto detectado. Os valores possíveis são os seguintes:
  FacialQuality getFacialQuality() {}

  // Indica se a pessoa usa óculos. Os valores possíveis são os seguintes:
  FacialGlasses getGlasses() {}

  // Valor numérico que indica a idade aproximada da pessoa.
  int getAge() {}

  // Gênero da pessoa. Os valores possíveis são os seguintes:
  FacialGender getGender() {}

  // Valor (0, 1) que indica a probabilidade de a pessoa usar uma máscara.
  float getFacialMask() {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}

Valores possíveis de FacialPose:

public enum FacialPose {
  // Desconhecido ou não calculado.
  None,

  // Olhando diretamente para a frente.
  Frontal,

  // Pessoa olhando para a direita.
  RightAngled,

  // Pessoa olhando para a esquerda.
  LeftAngled
}

Valores possíveis de FacialQuality:

public enum FacialQuality {
  None,
  Bad,
  Regular,
  Good
}

Valores possíveis de Glasses:

public enum Glasses {
  None,
  Eyes,
  Sun
}

Valores possíveis de Gender:

public enum Gender {
  None,
  Male,
  Feminino
}

3.9.2. SelphIDFacialAuthenticationResult

Apresenta diferentes propriedades para avaliar o resultado da Authentication biométrica:

public class SelphIDFacialAuthenticationResult {
  // Resultados de um processo de Authentication facial.
  FacialAuthenticationStatus getFacialAuthenticationStatus() {}

  // Valor de similaridade entre 0 e 1 que representa a similaridade entre os rostos das duas imagens.
  float getSimilarity() {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}

Importante

Para avaliar o resultado, você deve utilizar a propriedade FacialAuthenticationStatus; o valor similarity é usado apenas para fins estatísticos.

Valores possíveis de FacialAuthenticationStatus:

public enum FacialAuthenticationStatus {
  // A Authentication biométrica não pôde ser realizada.
  None,

  // Resultado negativo de Authentication.
  Negative,

  // OBSOLETO.
  Uncertain,

  // Resultado positivo de Authentication.
  Positive,

  // A Authentication biométrica não pôde ser realizada porque o ângulo máximo permitido entre os rostos de cada imagem fornecida foi excedido.
  NoneBecausePoseExceeded,

  // A Authentication biométrica não pôde ser realizada porque a extração de características biométricas não pôde ser realizada em nenhuma das imagens fornecidas.
  NoneBecauseInvalidExtractions
}

3.9.3. SelphIDDocumentResult

Apresenta diferentes métodos para recuperar as imagens usadas no processo e os dados lidos do documento. Os métodos são os seguintes:

public class SelphIDDocumentResult {
  // Obtém todas as chaves associadas a cada um dos dados lidos do documento.
  String[] listDocumentKeys() {}

  // Obtém um determinado dado lido do documento por meio de sua chave associada.
  String getDocumentValue(String key) {}

  // Obtém todas as chaves associadas a cada uma das imagens lidas do documento.
  String[] listImageKeys() {}

  // Obtém uma determinada imagem do documento por meio de sua chave associada.
  byte[] getImage(String key) {}

  // Obtém a lista de chaves de ExtraData.
  String[] listExtraDataKeys() {}

  // Obtém o valor de ExtraData para a chave fornecida.
  String getExtraDataValue(String key) {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}

3.9.4. SelphIDFacialLivenessResult

Apresenta a propriedade FacialLivenessDiagnostic para avaliar o resultado do diagnóstico de teste de vida passivo.

public class SelphIDFacialLivenessResult {
  // Obtém o diagnóstico de Liveness facial.
  FacialLivenessDiagnostic getFacialLivenessDiagnostic() {}

  // Adicionado em 6.18.0
  // Obtém informações adicionais quando o diagnóstico de Liveness facial é NoLive.
  SelphIDNoLiveDetails getNoLiveDetails() {}

  // Obtém o timestamp válido
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}

Valores possíveis de FacialLivenessDiagnostic:

public enum FacialLivenessDiagnostic {
  // O diagnóstico de Liveness não pôde ser avaliado.
  None,

  // Uma condição de fraude foi detectada, um vídeo ou uma fotografia.
  // OBSOLETO > use "NoLive".
  Spoof,

  // OBSOLETO.
  Uncertain,

  // O sujeito passa no diagnóstico de Liveness.
  Live,

  // O Liveness não pôde ser avaliado devido à baixa qualidade das imagens usadas.
  NoneBecauseBadQuality,

  // O Liveness não pôde ser avaliado porque o rosto está muito próximo da câmera.
  NoneBecauseFaceTooClose,

  // O Liveness não pôde ser avaliado porque nenhum rosto foi detectado nas imagens usadas.
  NoneBecauseFaceNotFound,

  // O Liveness não pôde ser avaliado porque foram detectados rostos muito pequenos nas imagens usadas.
  NoneBecauseFaceTooSmall,

  // O Liveness não pôde ser avaliado porque o ângulo entre os rostos foi excedido.
  NoneBecauseAngleTooLarge,

  // O Liveness não pôde ser avaliado devido ao formato das imagens usadas.
  NoneBecauseImageDataError,

  // O Liveness não pôde ser avaliado devido a um erro interno.
  NoneBecauseInternalError,

  // O Liveness não pôde ser avaliado devido a um erro no processamento das imagens usadas.
  NoneBecauseImagePreprocessError,

  // O Liveness não pôde ser avaliado porque há muitas pessoas na cena.
  NoneBecauseTooManyFaces,

  // O Liveness não pôde ser avaliado porque o rosto está muito próximo das bordas da imagem.
  NoneBecauseFaceTooCloseToBorder,

  // O Liveness não pôde ser avaliado porque a imagem usada está recortada.
  NoneBecauseFaceCropped,

  // O teste de vida não pôde ser avaliado devido a um erro de licença.
  NoneBecauseLicenseError,

  // O Liveness não pôde ser avaliado porque o rosto da pessoa está ocluído.
  NoneBecauseFaceOccluded,

  // A imagem não corresponde a uma pessoa real.
  NoLive,

  // O Liveness não pôde ser avaliado porque os olhos da pessoa estão fechados.
  NoneBecauseEyesClosed,

  // O Liveness não pôde ser avaliado porque os olhos da pessoa estão ocluídos.
  NoneBecauseEyesOccluded,

  // None devido a erro nos dados do Token ou formato incorreto.
  NoneBecauseTokenDataError,

  // None devido a quebra das medidas internas de segurança do Token.
  NoneBecauseTokenSecurity
}

A partir da Versão 6.18.0, a estrutura SelphIDNoLiveDetails com informações adicionais sobre o caso NoLive. No caso Live, também podemos consultar as pontuações (scores) do pipeline.

// Detalhes do SelphID para o caso FacialLivenessDiagnostic::NoLive.
public class SelphIDNoLiveDetails {
  // Causa principal em alto nível do diagnóstico NoLive.
  NoLiveMainCause getNoLiveMainCause() {}

  // Status da detecção de ataque de apresentação facial (fPAD).
  FPadStatus getFPadStatus() {}

  // Score fPAD normalizado (0..1), se disponível.
  float getFPadScore() {}

  // Status da detecção de ataque de manipulação facial (fMAD).
  FMadStatus getFMadStatus() {}

  // Score fMAD normalizado (0..1), se disponível.
  float getFMadScore() {}

  // Score de coerção normalizado (0..1), se disponível.
  float getCoercionScore() {}

  // Mensagem de motivo legível para humanos, para logs/Backoffice.
  String getReasonMessage() {}
}

3.9.5. SelphIDIdentifierResult

Apresenta diferentes métodos para obter as informações de comparação de cada um dos candidatos retornados como resultado de uma busca 1:N. São os seguintes:

public class SelphIDIdentifierResult {
  // Obtém o número de candidatos obtidos na busca.
  int size() {}

  // Obtém a similaridade a partir do índice do resultado.
  float getSimilarity(int index) {}

  // Obtém o índice da galeria a partir do índice do resultado.
  int getGalleryIndex(int index) {}

  // Obtém o templateID a partir do índice do resultado.
  String getTemplateID(int index) {}

  // Obtém o código de status da comparação realizada entre o template de busca e o candidato indicado.
  FacialAuthenticationStatus getFacialAuthenticationStatus(int index) {}

  // Obtém informações adicionais caso a comparação biométrica entre o template de busca e o candidato indicado tenha sido positiva.
  FacialAuthenticationDetail getFacialAuthenticationDetail(int index) {}
}

Valores possíveis de FacialAuthenticationStatus:

public enum FacialAuthenticationStatus {
  // A comparação biométrica não pôde ser realizada.
  None,

  // Os padrões faciais não correspondem.
  Negative,

  // OBSOLETO.
  Uncertain,

  // Os padrões faciais correspondem.
  Positive,

  // A comparação biométrica não pôde ser realizada porque o rosto em algumas das capturas está em um ângulo de rotação muito alto em relação à câmera.
  NoneBecausePoseExceed,

  // A comparação biométrica não pôde ser realizada porque nenhum rosto pôde ser detectado em nenhuma das capturas realizadas.
  NoneBecauseInvalidExtractions
}

Valores possíveis de FacialAuthenticationDetail:

public enum FacialAuthenticationDetail {
  // A comparação não foi bem-sucedida.
  None,

  // Os padrões faciais correspondem com uma baixa porcentagem de similaridade.
  PositiveLowSecurityLevel,

  // Os padrões faciais correspondem com uma porcentagem média de similaridade.
  PositiveMediumSecurityLevel,

  // Os padrões faciais correspondem com uma alta porcentagem de similaridade.,
  PositiveHighSecurityLevel
}

3.9.6. SelphIDVerifierResult

Apresenta diferentes métodos para obter informações do orquestrador. São os seguintes:

public class SelphIDVerifierResult {
  // Obtém informações sobre o documento.
  SelphIDDocumentResult getSelphIDDocumentResult() {}

  // Obtém informações sobre o processo de Authentication.
  SelphIDFacialAuthenticationResult GetSelphIDFacialAuthenticationResult() {}

  // Obtém informações sobre o processo de Liveness.
  SelphIDFacialLivenessResult GetSelphIDFacialLivenessResult() {}
}

Nota

Para mais informações:

• 3.9.2. SelphIDFacialAuthenticationResult

• 3.9.3. SelphIDDocumentResult

• 3.9.4. SelphIDFacialLivenessResult

3.9.7. SelphIDApiTrackingResult

Apresenta diferentes métodos para obter informações da operação da API Tracking. São os seguintes:

public class SelphIDApiTrackingResult {
  // Obtém o resultado HTTP da solicitação de Tracking.
  int GetTrackingStatus() {}

  // Obtém a mensagem da solicitação de Tracking.
  String GetTrackingMessage() {}
}

3.10. Descrição de SelphIDException

Se ocorrer um erro dentro do SelphID-SDK, a exceção SelphIDException será lançada.

public class SelphIDException extends Exception {
  // Obtém o tipo de exceção que ocorreu.
  SelphIDExceptionType getExceptionType() {}
}

Valores possíveis de SelphIDExceptionType:

public enum SelphIDExceptionType {
  // Erro no conteúdo da licença.
  ErrorLicenseContent,

  // A licença expirou.
  ErrorLicenseExpired,

  // Erro no HostID da licença.
  ErrorLicenseHostID,

  // Erro no template facial.
  ErrorFacialTemplate,

  // Erro ao carregar a biblioteca.
  // OBSOLETO.
  ErrorLoadingLibrary,

  // Erro no registro de uso da licença.
  ErrorLicenseUsageLogging,

  // Imagem facial com erro ou inválida.
  ErrorFacialImage,

  // Erro nos dados do documento.
  ErrorDocumentData,

  // Erro na licença de rede.
  ErrorLicenseNetwork,

  // Erro porque o número de conexões da licença de rede foi excedido.
  ErrorLicenseNetworkConnectionsExceeded,

  // Tamanho da galeria atingido.
  ErrorLicenseGallerySizeReached,

  // Opções inválidas.
  ErrorInvalidOptions,

  // Erro: a licença está muito antiga.
  ErrorLicenseTooOld,

  // Erro porque um recurso não está disponível.
  ErrorUnavailableFeature,

  // Erro porque o template facial é incompatível.
  ErrorIncompatibleFacialTemplate,

  // Erro ao acessar o arquivo de configuração.
  ErrorConfigurationFileAccess,

  // Erro ao acessar os dados de API Tracking.
  ErrorTrackingFileAccess,

  // Erro ao carregar o arquivo de configuração da API Tracking.
  // OBSOLETO.
  ErrorLoadingTrackingFile,

  // As variáveis de configuração do SelphID estão vazias (arquivo de configuração ou variáveis de ambiente).
  ErrorConfigVarsEmpty,

  // A chave `FACEPHI_SELPHID_INSTALL_PATH` está vazia.
  ErrorInstallPathEmpty,

  // A chave `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY` está vazia.
  ErrorLivenessDataPathEmpty,

  // Erro ao carregar a biblioteca de Authentication facial.
  ErrorLoadingFacialLibrary,

  // Erro ao carregar a biblioteca de Liveness.
  ErrorLoadingLivenessLibrary,

  // Erro interno ao executar a extração facial.
  ErrorProcessingFacial,

  // Erro interno ao executar a verificação de Liveness.
  ErrorProcessingLiveness,

  // Erro ao acessar uma galeria no disco.
  ErrorGalleryFile
}