Biometric ID - SDK - REACT NATIVE¶

En este documento encontrará una explicación de cómo se realiza la integración con el SDK BiometricID en React Native

El SDK solo funciona en dispositivos fisicos, no puede ser usado en emuladores.

Pre requisitos¶

Para hacer uso del SDK debe contar con un API Key válido.
El Bundle Identifier debe ser previamente autorizado para activar el uso del SDK
Debe tener un usuario creado desde el selfservice

Flujo de uso¶

El SDK está diseñado para utilizarse de manera secuencial, el flujo es el siguiente:

flowchart LR
    A([Consulta de documento]) --> B([Verificación biometrica])
    B --> C([Consulta de información adicional])

Modo de uso¶

Existen 2 formas de usar el SDK

Haciendo uso de los Componentes predefinidos
Haciendo uso de los Hook predefindos

Instalación del SDK¶

Prerequisitos de instalación¶

Debe recibir el token de instalación TOKEN_DE_INSTALACION
Debe descargar el zip con los componentes extra de instalación extras.zip

Instalación¶

Agregue las siguientes lineas al archivo .npmrc (creelo si no existe en la raíz del proyecto)

@getlatam:registry=https://pkgs.dev.azure.com/getlatam/Racsa/_packaging/BiometricID/npm/registry/

always-auth=true

Agregue las siguientes lineas al archivo .yarnrc.yml (creelo si no existe en la raíz del proyecto)

nodeLinker: node-modules
nmHoistingLimits: workspaces

npmScopes:
  getlatam:
    npmRegistryServer: https://pkgs.dev.azure.com/getlatam/Racsa/_packaging/BiometricID/npm/registry/
    npmAuthIdent: 'getlatam:TOKEN_DE_INSTALACION'
    npmAlwaysAuth: true

Agregue la siguiente linea al archivo package.json de su proyecto

  "packageManager": "yarn@3.6.1",

Instale los paquetes y dependencias necesarios:

    yarn install
    yarn add @getlatam/airsnap-ui
    yarn add @getlatam/biometric-id-sdk
    yarn add react-native-permissions
    yarn add react-native-svg
    yarn add react-native-paper

Copie la carpeta Frameworks en la ruta node_modules/@getlatam/airsnap-ui/ios

Android¶

En la carpeta android en settings.gradle agregue lo siguiente:

apply from: file("../node_modules/@getlatam/airsnap-ui/android/native_module.gradle"); 
applyT5NativeModulesSettingsGradle(settings);

Copie la carpeta models en la ruta android/app/src/main/assets/models
Copie la carpeta jniLibs en la ruta android/app/src/main/jniLibs
Abra el archivo build.gradle de la carpeta app y agregue la siguiente sección en dependencies:

    def camerax_version = '1.3.1'
    implementation "androidx.camera:camera-core:$camerax_version"
    implementation "androidx.camera:camera-camera2:$camerax_version"
    implementation "androidx.camera:camera-lifecycle:$camerax_version"
    implementation "androidx.camera:camera-view:$camerax_version"
    implementation 'com.google.android.material:material:1.9.0'

Agregue el permiso de Camera al archivo AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA"/>

Asigne un applicationid el archivo build.gradle de la ruta android/app

iOS¶

Reemplace el script del archivo Podfile que contiene este texto:

 # Resolve react_native_pods.rb with node to allow for hoisting
 require Pod::Executable.execute_command('node', ['-p',
   'require.resolve(
     "react-native/scripts/react_native_pods.rb",
     {paths: [process.argv[1]]},
   )', __dir__]).strip

con el siguiente:

 def node_require(script)
   # Resolve script with node to allow for hoisting
   require Pod::Executable.execute_command('node', ['-p',
     "require.resolve(
       '#{script}',
       {paths: [process.argv[1]]},
     )", __dir__]).strip
 end
node_require('react-native/scripts/react_native_pods.rb')
node_require('react-native-permissions/scripts/setup.rb')

Agregue setup_permissions(['Camera']) después de prepare_react_native_project! en el Podfile
Agregue las siguientes lineas después de config = use_native_modules!

  use_frameworks!
  pod 'OpenSSL-Universal'

Agrege el permiso de camara en el app Info.plist

<key>NSCameraUsageDescription</key>
<string>YOUR TEXT</string>

ejecute el comando

pod install

Abra el proyecto xcworkspace en xcode y copie la carpeta models en la raiz del proyecto creando las referencias a la carpeta y copiando los items

Parametros de configuración¶

El SDK debe ser usado dentro de un proveedor de estado `BiometricIdContextStateProvider``

...
import { BiometricIdContextStateProvider } from '@getlatam/biometric-id-sdk';
...
<BiometricIdContextStateProvider>
      ...
</BiometricIdContextStateProvider>

Configure el endpoint y apikey

...
import { BiometricIdStateContext, useBiometricIdSdkConfig } from "@getlatam/biometric-id-sdk";
...

  const { setSdkConfig } = useBiometricIdSdkConfig();
  useEffect(()=>{
      setSdkConfig({
        apiUrl: "https://apibiometricid.racsa.go.cr/bioapi",
        apiKey: "APIKEY"
      });
  },[]);

CUSTOMIZATION OF UI COMPONENTS IN ANDROID¶

Strings¶

String resources can be overridden in application and alternative strings for supported languages can be provided using standard Android localization mechanism

<string name="title">%s capture</string>  
<string name="title_left_hand">Left hand</string>  
<string name="title_right_hand">Right hand</string>  
<string name="title_left_thumb">Left thumb</string>  
<string name="title_right_thumb">Right thumb</string>  


<string name="label_sdk_init_failed">SDK initialization failed code( %d )</string>  
<string name="label_progress">Processing…</string>  
<string name="label_right">Right</string>  
<string name="label_left">Left</string>  
<string name="label_four_fingers">4 fingers</string>  
<string name="label_finger">finger</string>  
<string name="label_fingers">fingers</string>  
<string name="label_left_or_right_num_fingers">%1$s %2$d fingers</string>  
<string name="label_thumbs">Thumbs</string>  
<string name="label_thumb">thumb</string>  

<string name="label_right_index_finger">Right index finger</string>  
<string name="label_right_middle_finger">Right middle finger</string>  
<string name="label_right_ring_finger">Right ring finger</string>  
<string name="label_right_little_finger">Right little finger</string>  


<string name="label_left_index_finger">Left index finger</string>  
<string name="label_left_middle_finger">Left middle finger</string>  
<string name="label_left_ring_finger">Left ring finger</string>  
<string name="label_left_little_finger">Left little finger</string>  


<string name="label_too_few_fingers_detected">Too few fingers detected</string>  

<!-- ex: More than 2 fingers , More than 1 finger ,  
%1d -> expected finger count for specified position,  
%2s -> finger(expected count 1) or fingers(expected count > 1)  
-->  
<string name="label_too_many_fingers_detected">More than %1$d %2$s</string>  

<!--Hold Right 4 fingers vertcally, Hold Left 4 fingers vertcally -->  
<string name="hold_vertically">Hold %s vertically</string>  
<string name="hold_horizontally">Hold %s horizontally</string>  

<string name="label_too_far">Please bring your hand closer</string>  
<string name="label_too_close">Please move your hand further</string>  
<string name="label_low_focus">Low focus. Try to move hand</string>  
<string name="label_good_focus">Hold your hand steady</string>  

<string name="label_frame_hand">Frame %s</string>

Colours¶

Colours can be customized in application. To use custom colours override the specific colour.

<color name="bounding_boxes_border_color">#aa89CFF0</color>  
<color name="bounding_boxes_fill_color">#3000FF00</color>  
<color name="border_color_error">#FFFF2020</color>  
<color name="border_color_info">#FFDDDD00</color>  
<color name="border_color_pass">#FF00FF00</color>  
<color name="airsnapfinger_overlay_color">#4D5F717D</color>

CUSTOMIZATION OF UI COMPONENTS IN IOS¶

Strings¶

String resources can be overridden in application and alternative strings for supported languages can be provided using standard iOS localization mechanism. Add the strings in Localizable.strings file and add the desired language.

//frame 4 fingers
"label.frame" = "Frame %@";

//(More than 4 fingers) or (More than 1 finger)
"label.morethan_expected_fingers" = "More than %d %@";

"label.fingers" = "Fingers";

"label.finger" = "Finger";

//Hold Right 4 fingers horizontally
"label.hold_fingers_horizantally" = "Hold %@ horizontally";

"label.hold_fingers_vertically" = "Hold %@ vertically";

"label.tooFar" = "Please bring your hand closer";

"label.tooClose" = "Please move your hand further";

"label.lowFocus" = "Low focus. Try to move hand";

"label.goodFocus" = "Hold your hand steady";

"label.right_4_fingers" = "Right 4 fingers";

"label.left_4_fingers" = "Left 4 fingers";

"label.thumbs" = "Thumbs";

"label.right_thumb" = "Right thumb";

"label.left_thumb" = "Left thumb";

"label.right_index" = "Right index finger";

"label.right_middle" = "Right middle finger";

"label.right_ring" = "Right ring finger";

"label.right_little" = "Right little finger";

"label.left_index" = "Left index finger";

"label.left_middle" = "Left middle finger";

"label.left_ring" = "Left ring finger";

"label.left_little" = "Left little finger";

"label.right" = "Right";

"label.left" = "Left";

"label.four_fingers" = "4 fingers";

"label.left_or_right_num_fingers" = "%@ %d fingers";

"label.thumb" = "thumb";

"label.too_few_fingers_detected" = "Too few fingers detected";

Componentes¶

En caso de hacer uso de los componentes, están diseñadas con la siguiente secuencia, sin embargo cada una funciona de manera independiente, permitiendo al desarrollador control en el paso a paso de las vistas.

flowchart LR
    A([DocumentQueryView]) --> B([BiometricQueryView])
    B --> C([BiometricMatchView])

DocumentQueryView¶

Este componente permite ingresar los datos de consulta, en Tipo de documento y Número de documento

DocumentQueryView

El componente permite definir sus children para mostrar el texto de términos y condiciones,

Metodos:

onNext(documentNumber, documentType)

Acción a ser llamada al oprimirse el botón de Continuar

Se debe definir el email del usuario que está usando la aplicación, así como solicitar los tipos de documento disponibles.

    const userEmail:string = "usuarioautorizado@gmail.com";

    //uso del proveedor de estado y reducer
    const { state, dispatch } = useContext(BiometricIdStateContext);

    //Uso del hook useDocumentQuery
    const { documentQuery } = useDocumentQuery();

    //Destruturación para obtener el metodo para obtener los tipos de documento
    const { documentTypesQuery } = useDocumentTypesAvailable();

    //Reliza llamado al api para solicitar tipos de documento disponible, cuando la configuración del SDK esté disponible
    useEffect(()=>{
      documentTypesQuery();
    }, [state.sdkConfig]);

<DocumentQueryView onNext={() => {
                documentQuery(documentNumber, documentType, userEmail).then((documentQueryResult) =>{
                    if(documentQueryResult?.biometricAvailable === true){
                      //Show BiometricQueryView
                    }else{
                      console.log('Document not found')
                    }
                  }).catch(e =>{
                    console.log('Error', e);
                  });
                }}>
                <Text
                onPress={() => Linking.openURL("https://biometricid.racsa.go.cr/terminoscondiciones")}
                >
                Ver términos y condiciones
                </Text>
            </DocumentQueryView>

BiometricQueryView¶

Este componente permite iniciar la verificación biometrica por reconocimiento facial o captura de huella según estén disponibles los metodos de validación para el documento consultado.

BiometricQueryView

Info

A partir de esta vista se puede identificar el ID asociado a esta transacción.

 const { dispatch } = useContext(BiometricIdStateContext);

 const documentNumber = '123456';//Current document number suggested to pass as route paramaters

 const { biometricVerification } = useBiometricQuery();

    <BiometricQueryView
          onFaceCaptured={() => {
            console.log('Face captured');
          }}
          onFingerCaptured={(finger, fingerPrint) => {
            console.log('Finger captured');
            biometricVerification(finger, fingerPrint).then((biometricQueryResult) =>{
              if(biometricQueryResult.hit){
               //La huella obtenida de la persona pertenece al número de documento consultado
               //Show BiometricResultView
              }
              else{
                console.log(biometricQueryResult);
              }
            }).catch((e) =>{
              console.log('Error', e);
            });
          }}
          onFingerFailed={(error) => {
            console.log('Finger failed', error);
          }}
          onfaceFailed={() => {
            console.log('Face failed');
          }} 
          documentNumber={documentNumber} 
          requestPermissionsMessage={{    
            title: 'BiometricId Camera Permission',
            message:
              'BiometricIdneeds access to your camera ' +
              'so you can take fingerprints pictures.',
            buttonNeutral: 'Ask Me Later',
            buttonNegative: 'Cancel',
            buttonPositive: 'OK',
          }}>
    </BiometricQueryView>

BiometricMatchView¶

Este componente permite mostrar el resultado de la verificación biometrica exitosa en un formato estandarizado.

BiometricMatchView

    <BiometricResultView onFinish={()=>{
          console.log('onFinish')    
          //Acción a ser ejecutada al finalizar el contador de tiempo    
       }} onGetMoreInformation={()=>{
          console.log('onGetMoreInformation')
          //Acción a ser ejecutada al oprimir el botón de más información
          //Paso suguerido:
          //Mostrar fuentes adicionales disponibles
       }}>
    </BiometricResultView>

ExternalQueryView¶

Este componente permite mostrar el resultado de consultas de bases de datos externas

     <ExternalSourceView />

Hooks¶

useDocumentTypesAvailable¶

documentTypesQuery

Metodo que ejecuta la consulta de tipos de documento disponibles

useDocumentQuery¶

documentQuery

Metodo que ejecuta la consulta de tipos de documento disponibles

isRunningApiQuery

Booleana que indica si hay una petición al api ejecutandose

documentQueryViewModel

Modelo usado por el componente, para definir tipo de documento, número de documento y email

setDocumentQueryViewModel

Metodo que permite actualizar el documentQueryViewModel

useBiometricQuery¶

biometricQueryResult

Modelo donde se almacena el resultado de la consulta

isRunningApiQuery

Booleana que indica si hay una petición al api ejecutandose

biometricVerification

Metodo que ejecuta la consulta biometrica, debe ejecutarse después de obtener la huella o la foto de la persona