Ajustes avanzados

Introducción

En este apartado se amplía la información general del lanzamiento del SDK.

Información avanzada del lanzamiento del SDK

En esta sección se va a ampliar la información del apartado de "Lanzamiento Simplificado del SDK".

Añadir repositorio privado

Para tener acceso a nuestro repositorio privado, se requiere haber instalado previamente Cocoapods en la máquina.

Por cuestiones de seguridad y mantenimiento, los nuevos componentes de la SDKMobile se almacenan en unos repositorios privados que requieren de unas credenciales específicas para poder acceder a ellos. Esas credenciales deberá obtenerlas a través del equipo de soporte de Facephi. A continuación se indica como preparar el entorno para consumir los componentes:

• Primero instalamos el comando que nos dará acceso a usar cocoapods con Artifactory.

sudo gem install cocoapods-art

• En caso de utilizar un Mac con chip M1, pueden surgir errores durante la instalación es posible que surjan errores en el futuro, de ser así, se recomienda usar en cambio el siguiente comando:

sudo arch -arm64 gem install ffi; sudo arch -arm64 gem install cocoapods-art

En caso de tener problemas con la instalación, desinstalar completamente cocoapods y todas sus dependencias para hacer una instalación limpia.

• Necesitaremos añadir el repositorio a la lista del fichero netrc. Para ello, desde un Terminal, se ejecuta el siguiente comando:

$ nano ~/.netrc

Y copiamos el siguiente fragmento con los datos correspondientes al final del fichero:

machine facephicorp.jfrog.io
  login <USERNAME>
  password <TOKEN>

Es importante copiar de manera exacta el anterior fragmento de código. El indentado previo a las palabras login y password está formado por dos espacios.

• Finalmente se añadirá el repositorio que contiene dependencias privada:

pod repo-art add cocoa-pro-fphi "https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi"

Dependencias requeridas para la integración

Para evitar conflictos y problemas de compatibilidad, en caso de querer instalar el componente en un proyecto que contenga una versión antigua de las librerías de Facephi (Widgets), éstos deberán eliminarse por completo antes de la instalación de los componentes de la SDKMobile.

• Actualmente las librerías FacePhi se distribuyen remotamente a través de diferentes gestores de dependencias, en este caso, Cocoapods. Dependencias obligatorias que deben ser instaladas previamente (añadiéndolas al Podfile):

plugin 'cocoapods-art', :sources => [
  'cocoa-pro-fphi’
]

source 'https://cdn.cocoapods.org/'

target 'Example' do
  pod 'FPHISDKMainComponent',  '~> 2.3.0'

   post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXPANDED_CODE_SIGN_IDENTITY'] = ""
      config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
      config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
    end
  end
end
...
end

• Cuando se quiera actualizar dependencias, antes de ejecutar el pod install hay que usar el siguiente comando para actualizar el repositorio local:

  pod repo-art update cocoa-pro-fphi

Posibles incidencias

En el caso de que el integrador utilice un Macbook con Chip M1, cabe la posibilidad de que la instalación de cocoapods-art no se realice correctamente. Por ello, se debe tener en cuenta los siguientes puntos:

• Si cocoapods se ha instalado mediante Homebrew puede haber problemas.

• Se recomienda instalar cocoapods y cocoapods-art usando gem.

A continuación incluimos un script que permite realizar todos los pasos necesarios para dejar el entorno preparado para poder funcionar correctamente:

 #! /bin/zsh

install_cocoapods () {
    echo "Installing cocoapods with gem"
    # Creating new gems home if it doesnt't exist
    if [ ! -d "$HOME/.gem" ]; then
        mkdir "$HOME/.gem"
    fi
    # Adding to current session
    export GEM_HOME="$HOME/.gem"
    export PATH="$GEM_HOME/bin:$PATH"

    # Adding for future sessions
    if test -f "$HOME/.zshrc"; then
        echo 'Adding $GEM_HOME env var and then adding it to your $PATH'
        echo '' >> "$HOME/.zshrc"
        echo 'export GEM_HOME="$HOME/.gem"' >> "$HOME/.zshrc"
        echo 'export PATH="$GEM_HOME/bin:$PATH"' >> "$HOME/.zshrc"
        echo 'alias pod='arch -x86_64 pod'' >> "$HOME/.zshrc"
    fi

    # Installing cocoapods
    gem install cocoapods
    sudo arch -x86_64 gem install ffi
    which pod
    pod --version
    gem install cocoapods-art
}

uninstall_cocoapods_homebrew () {
    which -s brew
    if [[ $? != 0 ]] ; then
        echo "Homebrew not installed, skipping uninstalling cocoapods from homebrew"
    else
        brew uninstall cocoapods
    fi
}

if ! type "pod" > /dev/null; then
    echo "You don't have cocoapods installed..."
else
    echo "Trying to uninstall it from homebrew first"
    uninstall_cocoapods_homebrew
fi

install_cocoapods

En caso de usar xCode15 se deberá realizar la siguiente configuración:

Se deberá añadir -ld_classic en Other Linker Flags, en el Build Settings de la aplicación.

SDK initialization

Debe evitarse inicializar un controlador que no vaya a usarse.

Cada uno de los componentes tiene un controlador (Controller) que permitirá acceder a su propia funcionalidad. Antes de poder utilizarse, deberán inicializarse correctamente. Los pasos a seguir en la inicialización son:

Se inicializan los controladores que se van a utilizar.

Se decide si la licencia se incluirá a través de un String o con un servicio de licenciamiento remoto (consultar apartado 3.1), y se inicia la sdk.

Si la inicialización devuelve un .STATUS_OK el controlador del SDK estará listo para su uso.

 let trackingController = TrackingController(trackingError: { trackingError in
      self.log("TRACKING ERROR: \(trackingError)")
  })

// MANUAL License
SDKController.shared.initSdk(license: SdkConfigurationManager.LICENSE, output: { sdkResult in
    if sdkResult.finishStatus == .STATUS_OK {
        self.log("Licencia manual seteada correctamente")
    } else {
        self.log("La licencia manual no es correcta")
    }
}, trackingController: trackingController)

// AUTO License
SDKController.shared.initSdk(licensingUrl: SdkConfigurationManager.LICENSING_URL, apiKey: SdkConfigurationManager.APIKEY_LICENSING, output: { sdkResult in
    if sdkResult.finishStatus == .STATUS_OK {
        self.log("Licencia automática seteada correctamente")
    } else {
        self.log("Ha ocurrido un error al intentar obtener la licencia: \(sdkResult.errorType)")
    }
}, trackingController: trackingController)

Inyección de licencias

Como se ha comentado previamente, actualmente existen dos formas de inyectar la licencia:

a. Obteniendo la licencia a través de un servicio

A través de un servicio que simplemente requerirá una URL y un API-KEY como identificador. Esto evitaría problemas a la hora de manipular la licencia, así como la constante sustitución de dichas licencias a la hora de surgir algún problema con ella (malformación o modificación indebida, expiración de la licencia...)

// AUTO License
SDKController.shared.initSdk(licensingUrl: SdkConfigurationManager.LICENSING_URL, apiKey: SdkConfigurationManager.APIKEY_LICENSING, output: { sdkResult in
    if sdkResult.finishStatus == .STATUS_OK {
        self.log("Licencia automática seteada correctamente")
    } else {
        self.log("Ha ocurrido un error al intentar obtener la licencia: \(sdkResult.errorType)")
    }
}, trackingController: trackingController)

b. Inyectando la licencia como String

Se puede asignar la licencia directamente como un String, de la siguiente manera:

// MANUAL License
SDKController.shared.initSdk(license: SdkConfigurationManager.LICENSE, output: { sdkResult in
    if sdkResult.finishStatus == .STATUS_OK {
        self.log("Licencia manual seteada correctamente")
    } else {
        self.log("La licencia manual no es correcta")
    }
}, trackingController: trackingController)

Iniciar nueva operación

Cada vez que se desee iniciar el flujo de alguna operación nueva (ejemplos de operaciones serían: onboarding, authentication, videoCall,…) es esencial indicarle al SDKController que ésta va a comenzar, y así la SDK sabrá que las próximas llamadas de Componentes (también llamados Steps) formarán parte de dicha operación. Esto es necesario para trackear a la plataforma la información global de esta operación de forma satisfactoria.

Al iniciar un proceso o flujo, siempre se deberá realizar la llamada al método newOperation

Este método tiene 3 parámetros de entrada:

1. operationType: Indica si se va a hacer un proceso de ONBOARDING o de AUTHENTICATION

2. customerId: Id único del usuario si se tiene (controlado a nivel de aplicación)

3. steps: Lista de pasos de la operación si se han definido previamente

Hay 2 maneras de realizar este inicio de operación, dependiendo de si se conocen los pasos que formarán el flujo del proceso de registro o autenticación (en caso de que los componentes se ejecuten de forma secuencial y siempre de la misma forma) o, en caso contrario, de que el flujo no esté definido y sea desconocido (por ejemplo, el cliente final es el que decide el orden de ejecución de los componentes).

• Flujo conocido (aparecerá la operación trackeada en la plataforma con todos los pasos de la lista). Ejemplo de implementación:

SDKController.shared.newOperation(operationType: OperationType.X, customerId: "customerId", steps: [.SELPHI, .SELPHID, .OTHER("CUSTOM_STEP")], output: { _ in })

• Flujo desconocido (aparecerá la operación trackeada en la plataforma con puntos suspensivos). Ejemplo de implementación:

SDKController.shared.newOperation(operationType: OperationType.X, customerId: "customerId", output: { _ in})

sdkResult → Contiene en data la información de la operación creada.

Una vez creada la operación se podrán ejecutar los componentes de la SDK asociados a esta operación. Consultar la documentación específica de cada componente para saber cómo hacerlo.

Tipos de operación existentes

En la actualidad, existen las siguientes operaciones, durante las cuales se hacen uso de unos determinados Componentes (STEPS). A continuación se muestra una tabla con la relación entre operaciones y steps:

Operación (OperationType)	Componente (Step)	Descripción
ONBOARDING	SELPHI_COMPONENT SELPHID_COMPONENT	- Validación facial de un selfie contra la cara de un documento - Extracción del OCR del documento - Detección de vivacidad
AUTHENTICATION	SELPHI_COMPONENT	- Validación facial mediante plantillas - Detección de vivacidad

Esta lista se irá ampliando en próximas actualizaciones de la SDK, según vayan apareciendo nuevos componentes y casos de uso.

Opciones para el lanzamiento del componente

Una vez iniciado el SDK y creada una nueva operación se podrá lanzar el componente. Hay dos formas de lanzar el componente:

• [CON TRACKING] Esta llamada permite lanzar la funcionalidad del componente con normalidad, y trackeando los eventos internos al servidor de tracking:

let controller = ExampleController(
        data: exampleConfigurationData,
        output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)

• [SIN TRACKING] Esta llamada permite lanzar la funcionalidad del componente con normalidad, pero no se trackeará ningún evento al servidor de tracking:

let controller = ExampleController(
        data: videoCallConfigurationData, 
        output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launchMethod(controller: controller)

El método launch debe usarse por defecto. Este método permite utilizar tracking en caso de estar su componente activado, y no lo usará cuando esté desactivado (o no se encuentre el componente instalado).

Por el contrario, el método launchMethod cubre un caso especial, en el cual el integrador tiene instalado y activado el tracking, pero en un flujo determinado dentro de la aplicación no desea trackear información. En ese caso se usa este método para evitar que se envíe esa información a la plataforma.

Retorno de resultado

El resultado de cada componente será devuelto a través de la SDK manteniendo siempre la misma estructura de 3 campos:

1. finishStatus: Que nos indicará si la operación ha finalizado correctamente. Posibles valores FinishStatus.STATUS_OK, FinishStatus.STATUS_ERROR

2. errorType: Si finishStatus indica que ha habido un error, este campo tendrá la descripción del mismo.

3. data: Tendrá los datos de respuesta de la función del SDK. Este campo será diferente dependiendo del componente que se haya ejecutado. En la documentación de cada componente específico se desglosarán los diferentes campos que puede devolver este objeto.

En la documentación de cada componente específico se desglosarán los diferentes campos que puede devolver este objeto

Métodos auxiliares

En este apartado se incluyen otros controladores y operaciones auxiliares, algunos de ellos opcionales, y que pueden ser necesarios para la correcta finalización del flujo.

Estos campos son necesarios para la comunicación con el servicio de Facephi, en caso de querer realizar cualquier verificación y de desear realizar el tracking de una operación determinada.

Obtención del OperationId

SDKController.shared.getOperationId()

Obtención del OperationType

SDKController.shared.getOperationType()

Obtención del SessionId

SDKController.shared.getSessionId()

Obtención del CustomerID

SDKController.shared.getCustomerId(

Asignación del CustomerID

SDKController.shared.setCustomerId(customerId: customerId)