Face Liveness (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-liveness/<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.
opções.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 = {
  timeExpiresUrl: '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.

No iOS, as permissões de câmera e movimento devem ser concedidas com NSCameraUsageDescription e NSMotionUsageDescription de acordo com o exemplo projeto.

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();

Retornar

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.eyJyZXF1ZXN0SWQiOiIyY2QwMTkxZS1jNzc0LTRjZWEtYjliNC1hOGJhYjRiODEzNGQiLCJpc0FsaXZlIjp0cnVlLCJ0b2tlbiI6ImYyOWFhNmM0YjczMmYyYWNhZTJjOGMxZWYxZDUyN2FhMDY0ZTI1YTg1OWMyNWU2MzZhMzQ0MTAzMTgwMXZ1MDEiLCJ1c2VySWQiOiJlZmI1NTg5NS1lMmY0LTRkMjQtOGE4OS04NGI0Nzg3ZjViM2EiLCJpbWFnZVVybCI6ImltYWdlVXJsIiwicGVyc29uSWQiOiJwZXJzb25JZCIsInNka1ZlcnNpb24iOiIxLjAuNCIsImF0dGVtcHRJZCI6IjY1M2ZmYjg2ZmViZTZhMzJiZWMyOWM1ZSIsImlhdCI6MTY5ODY5MTk3NH0.BKCtQUbPRBMchHX30_fqf6vSWVN__K4nsOecKLoybGs"
}

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.
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. `

{% hint style="warning" %} O isAlive parâmetro é MUITO IMPORTANTE, com base nele, a validação deve ser realizada para continuar ou não com o fluxo, em caso de isAlive: true, seu usuário pode continuar com a jornada, em caso de isAlive: false, este usuário não é válido e deve ser impedido de continuar o restante da jornada. {% endhint %}

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

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.