Skip to main content

Captura de Selfie

Esta guía está diseñada para ayudarlo a implementar el SDK Web de forma rápida y fácil. Se proporcionan conceptos básicos, ejemplos de implementación de SDK y de cómo interactuar con las API REST del motor biométrico.

A través de esta guía, se puede:

  • Implementar la apertura de la cámara y la captura de imágenes;
  • Manipular los datos de devolución;
  • Utilizar la devolución del SDK con las API del motor biométrico.

Antes de comenzar, asegúrese de haber seguido las instrucciones paso a paso para instalar e importar el SDK en esta guía.

RECURSOS DISPONIBLES​

SDK Web ofrece un componente de captura de selfies que contiene una silueta que ayuda al usuario a posicionarse correctamente para la foto. La captura de selfie se puede realizar de tres maneras, que son:

CAPTURA MANUAL​

En este tipo de experiencia existe un frame de captura para ayudar al usuario a posicionar su rostro correctamente. Luego de posicionar correctamente, el usuario debe hacer clic en un botón para capturar la imagen.

El SDK no realiza ningún tipo de validación de lo que se está capturando. Si la imagen capturada no tiene un rostro biométricamente válido, las API rechazan el encrypted del motor biométrico.

Captura Manual

CAPTURA AUTOMÁTICA​

En este tipo de experiencia, el rostro del usuario se identifica automáticamente a través de algoritmos de visión computacional y se le ayuda a posicionarse correctamente dentro del área de captura. Después de posicionarse correctamente, la imagen se captura automáticamente.

Al ayudar al usuario a encuadrar su rostro en el área de captura, esta opción puede reducir los problemas al enviar el encrypted a las API del motor biométrico.

Captura Manual

SMARTLIVE CON INTERACCIÓN FACETEC​

En este tipo de experiencia, se instruye al usuario para que realice unos simples movimientos durante la captura, los cuales van acompañados de algoritmos de visión computacional para garantizar que en ese momento está tomando una foto.

Como requiere el movimiento del usuario, este tipo de captura tiene una capa extra de seguridad contra el fraude. Al igual que con la Captura Automática, la imagen se captura sin necesidad de que el usuario presione un botón. De esta forma se tiende a reducir los problemas a la hora de enviar el encrypted a las API backend del motor biométrico.

ACTIVACIÓN DE SMARTLIVE CON INTERACCIÓN FACETEC

La activación de la funcionalidad se puede verificar en el portal del cliente, como se explica en este artículo.

IMPLEMENTACIÓN​

Al seguir esta guía paso a paso, tendrá todo el potencial del SDK integrado en su aplicación Web.

  1. INICIALIZAR EL SDK​

    Como primer paso, debes realizar 3 sencillos pasos en su proyecto:

    Instancie un nuevo Builder:

    const unicoCameraBuilder = new UnicoCheckBuilder();

    Especifique el camino de los archivos adicionales (caso agregado en su proyecto):

    Ya no es obligatorio incluir recursos adicionales en su aplicación si usa el SDK con Interactive Liveness

    A partir de la versión 3.18.0, para que el SDK busque automáticamente recursos adicionales, basta con que no esté implementado el método setResourceDirectory y la configuración de CSP para uso del SDK se aplican correctamente.

    unicoCameraBuilder.setResourceDirectory("/resources");

    Especifique el camino de los archivos de los modelos de IA si usa la función de Cámara Inteligente.

    unicoCameraBuilder.setModelsPath("https://meusite.com.br/models");

  2. CONFIGURACIÓN DE IDIOMAS DE LA EXPERIENCIA DE CAPTURA​

    Es posible configurar la experiencia de los mensajes informativos de los marcos de captura cambiando su idioma. Para eso, utiliza el enumerador LocaleTypes que contiene los siguientes valores:

    LocaleTypes.PT_BR: para Portugués (Brasil)

    LocaleTypes.ES_MX: para Español(México)

    LocaleTypes.ES_ES: para Español(España)

    LocaleTypes.EN_US: para Inglés(EUA)

    A continuación, puedes ver un ejemplo de cómo implementar la configuración de idioma:

    import {
      ...
      UnicoCheckBuilder,
      LocaleTypes
      ...
    } from "unico-webframe"

    unicoCameraBuilder.setLocale(LocaleTypes.EN_US);
    Configuración predeterminada

    Si no se configura, por defecto, el SDK Web utiliza el Portugués (Brasil) como idioma principal.

    Informativa

    Si desea personalizar las cadenas de forma remota, comuníquese con el CSM de la cuenta;

  3. CONFIGURACIÓN DE ENTORNOS​

    Configuración predeterminada

    En caso de que no se haya configurado, por defecto el SDK web utiliza el entorno de producción.

    Es posible configurar el entorno que se utilizará en la ejecución del SDK. Utilice el enumerado SDKEnvironmentTypes que contiene los siguientes enumerados:

    SDKEnvironmentTypes.PROD: para entorno de producción

    SDKEnvironmentTypes.UAT: para entorno de homologación

    Vea cómo implementarlo en el ejemplo a continuación:

    import {
      ...
      UnicoCheckBuilder,
      SDKEnvironmentTypes
      ...
    } from "unico-webframe"

    unicoCameraBuilder.setEnvironment(SDKEnvironmentTypes.UAT);

  4. CONFIGURAR EL TAMAÑO DEL FRAME​

    PASO NO DEMANDADO PARA MODO SMARTLIVE CON INTERACCIÓN FACETEC

    Este paso solo es necesario si no está utilizando Smartlive con la interacción FaceTec, ya que en este modo el SDK renderiza un frame que ocupa todo el espacio de la pantalla y se ajusta automáticamente.

    Si no está utilizando Smartlive con interacción FaceTec, SE RECOMIENDA que configure el tamaño del frame dentro de su aplicación, para optimizar el área de captura dentro de su WebApp. Consulte a continuación cómo realizar esta configuración para Web Desktop o Mobile.

    SUGERENCIA

    Muchas veces el funcionamiento del frame puede verse afectado por algunos design-systems que tienen algún tipo de grid-system, como por ejemplo, bootstrap o material-ui. Para minimizar este riesgo, asegúrese de posicionar el frame (id="box-camera") en algún lugar del código que no herede reglas indeseadas de css.

    En las versiones Web Desktop, es posible restringir el tamaño del frame para que no utilice toda la dimensión de su WebApp. Para ello, simplemente envuelva el frame (id="box-camera") en otra tag html, como en el siguiente ejemplo:

    <div class="container">
      <div id="box-camera"></div>
    </div>

    Idealmente, debe intentar de mantener una proporción adecuada entre el alto y ancho, lo que facilita encuadrar el rostro del usuario. A continuación un ejemplo:

    .container {
      width: 800px;
      height: 600px;
      position: relative;
    }

    Siguiendo el ejemplo anterior, el frame respeta el tamaño del elemento "padre", en este caso representado por el contenedor. De esta manera, tiene la flexibilidad de implementar el frame de la manera más conveniente para su aplicación (Como en un modal, por ejemplo).

    PROBAR DIVERSOS TAMAÑOS DE PANTALLA

    Las pruebas que cambian el tamaño de la pantalla a través del modo de desarrollador de su browser no funcionan. Se recomienda que este tipo de prueba se realice cambiando el tamaño de la ventana de su browser.

  5. CONFIGURAR DISPOSICIÓN DEL FRAME​

    Esta es una etapa opcional, sin embargo, muy recomendable.

    Para personalizar el frame de captura con Theme Builder, simplemente genere una instancia de la clase UnicoThemeBuilder e invoque los métodos que personalizan cada una de las propiedades del frame de captura, como se ejemplifica a continuación:

    const unicoTheme = new UnicoThemeBuilder()
    .setColorSilhouetteSuccess("#0384fc")
    .setColorSilhouetteError("#D50000")
    .setColorSilhouetteNeutral("#fcfcfc")
    .setBackgroundColor("#dff1f5")
    .setColorText("#0384fc")
    .setBackgroundColorComponents("#0384fc")
    .setColorTextComponents("#dff1f5")
    .setBackgroundColorButtons("#0384fc")
    .setColorTextButtons("#dff1f5")
    .setBackgroundColorBoxMessage("#fff")
    .setColorTextBoxMessage("#000")
    .setColorCancelButton("#0384fc")
    .setColorProgressBar("#0384fc")
    .setHtmlPopupLoading(`<div style="position: absolute; top: 45%; right: 50%; transform:
    translate(50%, -50%); z-index: 10; text-align: center;">Carregando...</div>`)
    .build();

    Después de generar el objeto de tema, como se ejemplificó anteriormente, debe pasarse como parámetro al método setTheme del builder unicoCameraBuilder

    unicoCameraBuilder.setTheme(unicoTheme);

  6. Para una experiencia de autenticación más asociada a tu marca, puedes insertar y personalizar tu logotipo en tiempo real.

    Paso 1

    En una carpeta pública (mismo lugar donde se agregan las carpetas de modelos y recursos) del proyecto, agregue una carpeta con el nombre unico_custom_footer_logo. En la carpeta unico_custom_footer_logo agregue su archivo de logotipo en formato .svg con el nombre unico_custom_footer_logo.svg

    Nota de precaución

    Los nombres de carpeta y archivo deben ser correctos. De lo contrario, la implementación no funciona.

    Paso 2

    Haga referencia al nombre de la carpeta creada en la compilación del SDK usando el método setCustomFooterLogoDirectory, por ejemplo:

       unicoCameraBuilder.setCustomFooterLogoDirectory('/unico_custom_footer_logo')

    Después de completar los pasos, la personalización estará lista y podrá ver su logotipo en el marco de captura interactivo de Liveness.

  7. IMPLEMENTAR LAS FUNCIONES DE CALLBACK​

    Uno de los objetos que se debe pasar como parámetro al método responsable de renderizar el frame de captura es el callback. Este objeto deberá contener funciones de callback para casos de éxito y error, como se ejemplifica a continuación.

      const callback = {
        on: {
          success: (obj) => {
            console.log(obj.base64);
            console.log(obj.encrypted);        
          },
          error: (error) => {
            console.error(error)
            //confira na aba "Configurações" sobre os tipos de erros
          }
        }
      };

    Este objeto es obligatorio y si no se implementa correctamente (incluyendo todos los eventos de success o error) genera una excepción, que si no se trata, se muestra en la consola del usuario.

    ::alert importante

    El atributo Encrypted está estrictamente destinado a enviar la imagen a través de las API de Unico. No debes abrir ni serializar este atributo, ya que sus características pueden cambiar sin previo aviso. Su uso debe ser exclusivo en interacciones con APIs para garantizar la integridad y seguridad de los datos. Unico no es responsable de ningún daño resultante de esta práctica, ya que pueden ocurrir cambios de manera impredecible. :::

    Para obtener más detalles sobre los códigos de error devueltos por el SDK, consulte esta guía.

  8. CONFIGURAR MODO DE CAPTURA E INICIAR LA CÁMARA​

    Para iniciar la cámara con las configuraciones realizadas hasta aquí, se debe crear una instancia del builder a través del método build().

    const unicoCamera = unicoCameraBuilder.build();

    Luego, con la cámara "montada", se debe configurar el modo de captura de la cámara.

    Si no está utilizando el modo Smartlive con la interacción FaceTec, en este paso puede elegir entre el modo de captura Manual o Automático.

    SUGERENCIA

    Si está utilizando el modo Smartlive con la interacción FaceTec, la configuración del tipo de cámara se vuelve irrelevante, ya que este modo ofrece una experiencia predefinida que no se puede cambiar.

    Sin embargo, se recomienda que configure un tipo de cámara en su builder (como se describe en este paso), porque si deshabilita el modo Liveness con la interacción FaceTec en su portal de clientes (y genera un nuevo JSON), no necesita cambiar su código.

    La cámara se preparará a partir del método prepareSelfieCamera(), disponible a partir del builder. Este método recibe 2 parámetros:

    • El archivo JSON con sus credenciales (generado a través de este guía);
    • Modo de cámara deseado, ellos son:
      • SelfieCameraTypes.NORMAL para el modo cámara normal;
      • SelfieCameraTypes.SMART para el modo cámara inteligente;

    Este método genera una promise que al ser resuelta, devuelve un objeto que se utiliza para realmente abrir la cámara a través del método open, que recibe como parámetro las funciones de callback configuradas en este paso.

    CONVIENE RECORDAR

    Para optimizar la apertura de la cámara se puede separar las llamadas de los métodos prepareSelfieCamera() y open(). Vea un ejemplo en esta POC realizada en React con TypeScript.

    Captura manual​

    Si desea utilizar la captura manual, cambie el parámetro Unico.SelfieCameraTypes.NORMAL al método prepareSelfieCamera.

    Usando la clase UnicoConfig:

      const config = new UnicoConfig()
        .setProjectNumber("<YOUR_PROJECT_NUMBER>")
        .setProjectId("<YOUR_PROJECT_ID>")
        .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
        .setHostname("<YOUR_HOSTNAME>")
        .setHostInfo("<YOUR_HOST_INFO>")
        .setHostKey("<YOUR_HOST_KEY>");
        
      unicoCamera.prepareSelfieCamera(
        config, 
        SelfieCameraTypes.NORMAL
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // revisa la pestaña "Referencias" para posibles errores
      });

    Usando el archivo json:

      unicoCamera.prepareSelfieCamera(
        "/services.json", 
        SelfieCameraTypes.NORMAL
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // revisa la pestaña "Referencias" para posibles errores
      });

  9. CONFIGURAR EL MODO DE CAPTURA DE VIDA INTERACTIVA EN IFRAME​

    Es posible utilizar el SDK web con Interactive Liveness integrado en un iFrame. Para ello, es necesario realizar una implementación similar a la sección anterior al preparar la cámara.

    La preparación de la cámara se llevará a cabo utilizando el método prepareSelfieCameraForIFrame(), también disponible en el constructor. Este método recibe los mismos parámetros que prepareSelfieCamera(): ​

    const unicoCamera = unicoCameraBuilder.build();

    const config = new UnicoConfig()
      .setProjectNumber("<YOUR_PROJECT_NUMBER>")
      .setProjectId("<YOUR_PROJECT_ID>")
      .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
      .setHostname("<YOUR_HOSTNAME>")
      .setHostInfo("<YOUR_HOST_INFO>")
      .setHostKey("<YOUR_HOST_KEY>");

      unicoCamera.prepareSelfieCameraForIFrame(
        config, 
        SelfieCameraTypes.SMART
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // revisa la pestaña "Referencias" para posibles errores
      });
    PREPARAR EL COMPORTAMIENTO DE LA CÁMARA

    El método prepareSelfieCameraForIFrame() solo funciona si la implementación está en un iFrame; usarlo fuera de un iFrame genera el error 73724. Al igual que usar el método prepareSelfieCamera() dentro de un iFrame genera el error 73724.

    IMPLEMENTACIÓN DEL ELEMENTO IFRAME​

    Para que la captura funcione correctamente es necesario implementar el elemento <iframe> como en el siguiente ejemplo:

    <iframe enable="fullscreen;camera;geolocalización" enableFullScreen src="your_app_url"></iframe>
    COMPORTAMIENTO EN PANTALLA COMPLETA​

    Para realizar la captura, debe estar en modo de navegador de pantalla completa para que el SDK pueda cambiar su tamaño automáticamente. Por lo tanto, al ejecutar la captura, el SDK muestra una pantalla solicitando abrir el fotograma en modo de pantalla completa. Vea el siguiente ejemplo:

    Solicitação do SDK para modo tela cheia

    Después de permitir el uso de pantalla completa, el marco de captura se abrirá normalmente:

    Frame de captura
    COMPORTAMIENTO EN IPHONES

    Apple impide el uso de API de pantalla completa específicamente en iPhone (los iPad son aceptables). Por tanto, para capturas en iPhone, es necesario configurar tú mismo el posicionamiento del iFrame.

  10. LLAMAR LAS APIS​​

    La captura de las imágenes es solo la primera parte del viaje. Después de capturar la imagen, es necesario enviar el Encrypted generado a las API, seleccionando uno de los flujos disponibles detallados en Flujos.

    Atención

    Por motivos de seguridad, el intervalo entre la generación del Encriptado y su envío a través de uno de los flujos disponibles debe ser de un máximo de 10 minutos. Los envíos realizados más allá de este período serán rechazados automáticamente por la API.

¿Dudas?​

¿No encontró algo o aún necesita ayuda? Si ya es cliente o asociado, puede contactarnos a través del Centro de Ayuda.