Face Authenticator (DESCONTINUADO)

Importando SDK

Para usar o Sdk, você pode importar remotamente o .js arquivo ou baixá-lo localmente.

Remotamente

Inclua o .js arquivo diretamente da CDN:

<script src="https://repo.combateafraude.com/javascript/release/face-authenticator/<VERSION>.js" type="text/javascript"></script>

Você pode obter a classe do SDK usando o seguinte código:

const sdk = window['FacesSDK'];

Inicialização

initializeSdk(token: string, sdkContainer: string, useFaceAuthenticator: boolean, personId: string, options: any)

O SDK possui um método de inicialização isolado, para permitir maior controle sobre quando ele ocorre.

Durante esse processo, o SDK inicializará suas variáveis internas e baixará os recursos necessários para sua execução.

[!]Você deve chamar este método antes de usar outros métodos do SDK.

Parâmetros suportados

Parâmetro	Obrigatório?
token Token de autenticação para consumir o SDK.	Sim.
sdkContainer Id do contêiner onde o SDK será inserido.	Sim.
useFaceAuthenticator Flag indicando se o FaceAuthenticator será usado.	Não. O padrão é false
personId Número do documento usado como identificador único para cada usuário.	Sim.
options.timeExpiresUrl Personalização do tempo de expiração da Url da imagem retornada pelo Sdk.	Não. O padrão é 30 minutos, os valores aceitos são 3H ou 30D.
options.settings.filter Personalização do filtro de captura de imagem.	Não. O padrão é sombreado
options.settings.language Personalização do idioma.	Não. O padrão é pt_BR
options.startButton.label Personalize o texto do botão de início do SDK.	Não.
options.startButton.color Personalize a cor do texto do botão de início do SDK.	Não.
options.startButton.backgroundColor Personalize a cor de fundo do botão de início do SDK.	Não.
options.startButton.borderRadius Personalize o raio da borda do botão de início do SDK.	Não.
options.startButton.border Personalize a borda do botão de início do SDK.	Não.
options.reverseProxy Veja mais detalhes na Configuração de proxy reverso seção.	Não.

Exemplo

const options = {
  timeExpiresrUrl: '30D',
  settings: {
    filter: 'classic',
    language: 'pt_BR'
  },
  startButton: {
    label: 'Escanear rosto',
    color: '#F9F9F9',
    backgroundColor: 'blue',
    borderRadius: '0.25rem',
    border: '1px solid #2D994B'
  }
}

const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);

Filtro

Configuração do filtro para a pré-visualização da câmera. Pode ser clássico, sombreado (detalhe adicional, o padrão), vibrante (cores completas), limpo (sem filtro) e desfocado (começa desfocado).

Idioma

Por meio do language parâmetro, o idioma do aplicativo pode ser alterado, o valor padrão é pt_BR, confira a disponibilidade abaixo:

Parâmetro	Idioma
cy_GB	Galês.
de	Alemão.
en	Inglês.
es	Espanhol.
fr	Francês.
it	Italiano.
nl	Holandês.
pt_BR	Português.

Iframe

Para realizar a integração por meio de um iframe, as permissões de câmera e tela cheia devem ser fornecidas.

<iframe
  src="https://caf.example"
  allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;"
></iframe>

Configuração de proxy reverso

Se você escolher usar um proxy reverso, deverá configurá-lo para encaminhar corretamente as solicitações para os endpoints apropriados. Abaixo está o mapeamento para redirecionamento:

• /v1/ → https://api.public.caf.io/v1/sdks/faces/

  • Considere usar https://api.public.beta.caf.io/v1/sdks/faces/ para homologação.
• /std/ → https://us.rp.secure.iproov.me/
• /std/ws/ → wss://us.rp.secure.iproov.me/ws/
• /assets/ → https://cdn.iproov.app/

Exemplo de configuração do SDK

Supondo que seu domínio seja my.proxy.io, sua configuração do SDK seria assim:

reverseProxy: {
    authBaseUrl: "https://my.proxy.io/v1/",
    livenessBaseUrl: "https://my.proxy.io/std/",
    assetsBaseUrl: "https://my.proxy.io/assets/"
}

Observação: Os caminhos fornecidos neste exemplo são apenas para referência. Você pode configurar seu proxy e caminhos de acordo com seus padrões de melhores práticas.

Webview

Para usar o SDK por meio de um Webview, a permissão de câmera deve ser concedida em seu aplicativo nativo.

Exemplo de implementação no Android.

AndroidManifest.xml

  <uses-permission android:name="android.permission.CAMERA" />
  <uses-feature
      android:name="android.hardware.camera"
      android:required="true" />

MainActivity

  @Override
  public void onPermissionRequest(final PermissionRequest request) {
      request.grant(request.getResources());
  }

Exemplo android projeto para implementação webview, além disso é necessário poder abrir o aplicativo em tela cheia, o exemplo mostra como configurá-lo corretamente.

Abertura e captura de selfies

execute()

O método usado para carregar o SDK na tela e realizar a captura de selfie.

Ele inicializará o stream (solicitando permissões, se necessário) e o carregará no contêiner.

Exemplo

await facesSdk.execute();

Retorno

Campo	Tipo	Descrição
signedResponse	string	Resposta assinada do servidor da CAF confirmando que a selfie capturada tem um rosto real. Este parâmetro é usado para obter uma camada extra de segurança, verificando se a assinatura da resposta não está quebrada ou se foi causada por interceptação da solicitação. Se estiver quebrada, há uma forte indicação de interceptação da solicitação.

Exemplo

{
   "signedResponse": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXF1ZXN0SWQiOiI1ZmUzOTliNi05MWFhLTQ0NmItOWU0OS0yZmM2OGNjMzJiYzciLCJtZXNzYWdlIjoiU3VjY2Vzc2Z1bGx5IiwicGVyc29uSWQiOiJwZXJzb25JZCIsImF0dGVtcHRJZCI6IjY1M2ZmY2NkYjlmMWQ2MjM4ODIyZmJmMCIsImlzTWF0Y2giOnRydWUsImlzQWxpdmUiOnRydWUsInRva2VuIjoiYWRkZDNkYmYwZDE1MGE0NTc1ZTI1N2VmZGFjNWNkN2ZkNWZlYTlmMWFkNjIyY2VlODY2ZmZjMjIxODAxdnUwMSIsInVzZXJJZCI6Ijg5NTQ0MDEzLTc0MDktNGQ0My04ZDFkLTM4NDVlY2E5MzMwNiIsImltYWdlVXJsIjoiaW1hZ2VVcmwiLCJzZGtWZXJzaW9uIjoiaXByb292QDEuMC40IiwiaWF0IjoxNjk4NjkyMzAxfQ.VW8OQShaC7UNy_e9xZ5isKgc9f9JElfMAVsV_dPf8G0"
}

Parâmetros da resposta assinada

Evento	Descrição
requestId	Identificador da solicitação.
isAlive	Validação de uma pessoa viva, identifica se o usuário passou com sucesso ou não.
isMatch	Resultado da validação da correspondência facial.
token	Token da solicitação.
userId	Identificador do usuário fornecido para a solicitação.
imageUrl	Link temporário para a imagem, gerado pela nossa API.
personId	Identificador do usuário fornecido para o SDK.
sdkVersion	Versão do Sdk em uso.
iat	Expiração do token.
message	Mensagem de retorno.

O isAlive parâmetro é MUITO IMPORTANTE, com base nele a validação deve ser feita para continuar ou não com o fluxo; no caso de isAlive: true seu usuário pode continuar com a jornada; no caso de isAlive: false, este usuário não é válido e deve ser impedido de seguir o restante da jornada. Além disso, o isMatch parâmetro indica se o Face Match foi bem-sucedido ou não, retornando isMatch: true em caso de sucesso e false em caso de falha.

Eventos

Atualmente o SDK emite três tipos de eventos:

Evento	Descrição
started	Inicialização do fluxo de captura.
sdk-button-ready	Os componentes do SDK foram carregados e estão prontos para uso.
passed	A captura da imagem foi bem-sucedida.
failed	A captura da imagem falhou.
error	Ocorreu um erro durante o processo de captura.
streaming	streaming iniciado, início em tela cheia.
streamed	Fim do streaming, encerrando a tela cheia.
canceled	Cancelamento do fluxo de captura.
unsupported	O navegador não oferece suporte ao Sdk.

Detalhes do evento de falha

O evento failed é do tipo customEvent portanto, se você desejar obter detalhes sobre o motivo da falha, pode consumir o event.detail onde você encontrará as seguintes descrições.

Feedback	Motivo	LA	GPA
eyes_closed	Mantenha os olhos abertos	✅	✅
face_too_far	Aproxime o rosto da tela	❌	✅
face_too_close	Afaste o rosto da tela	❌	✅
misaligned_face	Mantenha o rosto dentro do oval	❌	✅
multiple_faces	Certifique-se de que apenas uma pessoa esteja visível	✅	✅
obscured_face	Remova quaisquer coberturas faciais	✅	✅
sunglasses	Remova os óculos de sol	✅	✅
too_bright	A luz ambiente está muito forte ou o brilho da tela está muito baixo	✅	✅
too_dark	Seu ambiente parece estar escuro demais	✅	✅
too_much_movement	Por favor, fique parado	❌	✅
unknown	Tente novamente	✅	✅

Exemplo de listener do evento de falha

document.addEventListener(
  "failed",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);

Detalhes do evento de erro

O evento error é do tipo customEvent portanto, se você desejar obter detalhes sobre o motivo do erro, pode consumir event.detail, onde encontrará as seguintes descrições.

Feedback	Motivo
unknown	Tente novamente
client_camera	Houve um erro ao obter o vídeo da câmera
client_error	Ocorreu um erro desconhecido
error_asset_fetch	Não foi possível buscar os assets
error_camera	A câmera não pode ser iniciada por motivos desconhecidos
error_camera_in_use	A câmera já está em uso e não pode ser acessada
error_camera_not_supported	A resolução da câmera é muito pequena
error_camera_permission_denied	O usuário negou nossa solicitação de permissão de câmera
error_device_motion_denied	O usuário negou nossa solicitação de permissão de movimento do dispositivo
error_device_motion_unsupported	Seu dispositivo aparentemente não informa totalmente o movimento do dispositivo
error_fullscreen_change	Saiu da tela cheia sem concluir o iProov
error_invalid_token	O token interno do sdk é inválido
error_network	Erro de rede
error_no_face_found	Nenhum rosto pôde ser encontrado
error_not_supported	O dispositivo ou a integração não consegue executar o Web SDK
error_server	Ocorreu um erro ao comunicar-se com os servidores do iProov
error_token_timeout	O token foi solicitado muito tempo depois de ter sido criado
error_too_many_requests	O serviço está sob alta carga e o usuário deve tentar novamente
error_user_timeout	O usuário iniciou a solicitação, mas não fez o streaming a tempo
integration_unloaded	O SDK foi desmontado do DOM antes de terminar
sdk_unsupported	O SDK atingiu o fim da vida útil e não tem mais suporte

Exemplo de listener do evento de erro

document.addEventListener(
  "error",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);

Erros

Todos os erros são instâncias do objeto Error Para entender a causa de um erro, você pode acessar error.name e error.message propriedades, que fornecem os seguintes detalhes:

Nome	Mensagem	Método
CameraPermissionDeniedError	Erro: permissão da câmera negada pelo usuário.	initializeSdk
CameraPermissionError	Erro ao obter permissão da câmera.	initializeSdk
CameraUnsupportedError	A câmera não é suportada por este navegador.	initializeSdk
RequestTokenError	Erro ao solicitar um token.	initializeSdk
RenderCaptureWindowError	Erro ao renderizar a janela de captura.	initializeSdk
CaptureError	Erro ao capturar uma imagem.	execute
FaceLivenessError	Erro durante a detecção de vivacidade facial.	execute
FaceLivenessError	Nenhum rosto pôde ser encontrado na selfie enviada.	execute
FaceLivenessError	Muitas solicitações em um curto período de tempo.	execute
FaceAuthenticationError	Erro durante a autenticação facial.	execute

Exemplo de tratamento de um initializeSdk error

  try {
    const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);
  } catch (error) {
    console.log("Nome do erro:", error.name); // RequestTokenError 
    console.log("Mensagem do erro:", error.message); // Error while requesting a token.
  }

Exemplo de tratamento execute error

  try {
    await facesSdk.execute();
  } catch (error) {
    console.log("Nome do erro:", error.name); // CaptureError 
    console.log("Mensagem do erro:", error.message); // Error while capturing an image.
  }

Observação: O detalhes do evento de erro capturar erros específicos que ocorrem durante o processo de detecção de vivacidade, enquanto a erros seção se refere a funcionalidades mais gerais e fundamentais do SDK. Dependendo da implementação, talvez seja necessário lidar com ambos os tipos de erro para garantir uma integração robusta.