Uso básico

Ejemplo básico de integración del SDK Web.

La siguiente guía muestra un ejemplo de integración en un entorno TypeScript + VITE. Este mismo proceso puede realizarse el los frameworks actuales con las diferencias que el entorno requiera (Sintaxis, Definición de componentes, etc).

Este ejemplo se basa en una integración básica. Es posible cambiar el comportamiento del flujo con las configuraciones o cambios requeridos.

En esta integración se utilizarán los componentes SDK Provider, SelphID Widget, Selphi Widget y Tracking (incluido en SDK Provider).

---

Instalación del componente

Instalar la librería SDK Web:

npm install @facephi/sdk-web-wc@latest

No olvidar preparar el archivo .npmrc con las credenciales para la descarga.

Definir los custom elements:

// main.ts
import '@facephi/sdk-web-wc';
import { defineCustomElements as defineFacephiSDKCustomElements } from '@facephi/sdk-web-wc/loader';

defineFacephiSDKCustomElements(window);

---

Integración y configuración del SDK Provider

Integrar el SDK Provider y configurarlo:

index.html

<section class="facephi-sdk-provider">
    <facephi-sdk-provider
        apikey="%VITE_LICENSE_KEY%"
        steps="START,SELPHID_WIDGET,SELPHI_WIDGET,FINISH"
    	type="ONBOARDING"
        customer-id="unique_user_id"
        language="en"
    >
    </facephi-sdk-provider>
</section>

Lógica de SDK Provider:

facephi-sdk-provider.ts

import { initSelphidWidget } from './facephi-selphid-widget';
import { ErrorData } from '@facephi/sdk-web-wc';

(async () => {
	await customElements.whenDefined('facephi-sdk-provider');

	// SDK Provider event handlers
	function handleEmitData(event: CustomEvent<{ operationId: string; sessionId: string; extraData: string }>) {
		const result = event.detail;
		console.log('[FACEPHI SDK PROVIDER] onEmitData', result);
	}

	function handleEmitError(event: CustomEvent<ErrorData>) {
		const result = event.detail;
		console.error('[FACEPHI SDK PROVIDER] onEmitError', result);
	}

	const sdkProvider = document.querySelector('facephi-sdk-provider');
	if (sdkProvider) {
		sdkProvider.addEventListener('emitData', handleEmitData);
		sdkProvider.addEventListener('emitError', handleEmitError);
		
		// Initializes the SelphID widget
		initSelphidWidget(sdkProvider);
	}
})();

Lógica de SelphID Widget:

facephi-selphid-widget.ts

import {
	Language,
	type ExtractionFinishEvent,
} from '@facephi/selphid-web-component';
import { initSelphiWidget } from './facephi-selphi-widget';

const SELPHID_CONFIG = `
    	<facephi-selphid-widget 
	        country="GB" 
	        language="${Language.EN}" 
	></facephi-selphid-widget>
`;

export function initSelphidWidget(sdkProvider: { innerHTML: string }) {
	sdkProvider.innerHTML = SELPHID_CONFIG;
	const selphidWidget = document.querySelector('facephi-selphid-widget');

	// SELPHID EVENTS
	function handleExtractionFinish(event: CustomEvent<ExtractionFinishEvent>) {
		const result = event.detail.detail;
		Logger.printLog(LoggerType.SELPHID, 'extractionFinish', result);

		// Initialize Selphi
		initSelphiWidget(sdkProvider);
	}
	
	// otros eventos

	if (selphidWidget) {
		selphidWidget.addEventListener('extractionFinish', handleExtractionFinish);
	}
}

Lógica de Selphi Widget

facephi-selphi-widget.ts

import {
	Language,
	type ExtractionFinishEvent,
} from '@facephi/selphi-web-component';

const SELPHI_CONFIG = `
	<facephi-selphi-widget 
		stabilization-stage="true" 
	        language="${Language.EN}" 
	        interactible="true" 
	        preview-image="true" 
	        timeout="30000" 
	        show-log="false"
	></facephi-selphi-widget>
`;

export function initSelphiWidget(sdkProvider: { innerHTML: string }) {
	sdkProvider.innerHTML = SELPHI_CONFIG;
	const selphiWidget = document.querySelector('facephi-selphi-widget');

	//SELPHI EVENTS
	function handleExtractionFinish(event: CustomEvent<ExtractionFinishEvent>) {
		const result = event.detail.detail;
		console.log('[FACEPHI SELPHI] extractionFinish', result);

		// Finish onboarding process with any logic
		sdkProvider.innerHTML = '<div class="onboarding-finished">ONBOARDING FINISHED</div>';
	}
	
	// Otros eventos

	if (selphiWidget) {
		selphiWidget.addEventListener('extractionFinish', handleExtractionFinish);
	}
}

Esto es sólo una aproximación. Es posible utilizar diferentes tipos de integración o sintaxis.

En este ejemplo sólo se ha tomado en cuenta el camino feliz, por lo que el resto de eventos también requieren ser integrados en implementaciones reales.

---

Integración y configuración de flujo de componentes

Este ejemplo es una integración del Happy Path para un Onboarding realizado mediante SelphID y Selphi.

Primero, con la instanciación del SDK Provider, se producirá la lógica interna para inicializar todos los servicios (Carga, Licenciamiento, Inicialización de Tracking, etc).

Cuando el Provider emita el evento emitData, se cargará el primer widget (SelphID) mediante la lógica de initSelphidWidget(sdkProvider).

Una vez el usuario haya completado el proceso de captura, el Widget SelphID se cerrará a la vez que emitirá el evento extractionFinish. En este evento se trabajarán los datos como se necesite y se cargará el siguiente componente (Selphi) con el método initSelphiWidget(sdkProvider);.

Por último, cuando el usuario termine de realizar la extracción del patrón facial, se trabajará con los datos obtenidos como se necesite y se terminará el flujo continuando con la lógica que se quiera.

Flujo entre componentes

En entornos más completos como pueden ser los frameworks actuales, es posible utilizar Componentes, Routers, Stores y todo tipo de herramientas para realizar dicho flujo.

El equipo de Facephi recomienda utilizar componentes y routers para una integración más modular, sencilla y rápida en el framework que se desee.

---

Pruebas de comportamiento

Una vez terminada la integración, es muy recomendable probar en el entorno de desarrollo de la aplicación que el funcionamiento es el esperado, teniendo en cuenta las posibles configuraciones y casuísticas que pudiesen aparecer en el flujo de los usuarios finales.

---