Basic usage

Basic Web SDK integration example.

The following guide shows an integration example in a TypeScript + VITE environment. This same process can be carried out in current frameworks, with the differences required by the environment (syntax, component definition, etc.).

This example is based on a basic integration. It is possible to change the behavior of the Flow with the required configurations or changes.

In this integration, the SDK Provider, SelphID Widget, Selphi Widget, and Tracking components (included in SDK Provider) will be used.

---

Component installation

Install the SDK Web library:

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

Don't forget to prepare the file .npmrc with the credentials for the download.

Define the custom elements:

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

defineFacephiSDKCustomElements(window);

---

Integration and configuration of the SDK Provider

Integrate the SDK Provider and configure it:

App.tsx

import { Language, TrackingSteps, TypeFamily } from '@facephi/sdk-web-wc';

<section className="facephi-sdk-provider">
  <facephi-sdk-provider
    apikey={import.meta.env.VITE_LICENSE_KEY}
    steps={`${TrackingSteps.start},${TrackingSteps.selphidWidget},${TrackingSteps.selphiWidget},${TrackingSteps.finish}`}
    type={TypeFamily.onboarding}
    customerId={customerId}
    language={Language.en}
  />
</section>

SDK Provider logic:

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

SelphID Widget logic:

facephi-selphid-widget.ts

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

export function initSelphidWidget(sdkProvider: HTMLElement) {
	sdkProvider.innerHTML = '';
	const selphidWidget = document.createElement('facephi-selphid-widget');
	selphidWidget.country = 'GB';
	sdkProvider.appendChild(selphidWidget);

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

		// Initialize Selphi
		initSelphiWidget(sdkProvider);
	}
	
	// other events

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

Selphi Widget logic

facephi-selphi-widget.ts

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

export function initSelphiWidget(sdkProvider: HTMLElement) {
	sdkProvider.innerHTML = '';
	const selphiWidget = document.createElement('facephi-selphi-widget');
	selphiWidget.stabilization = true;
	selphiWidget.interactible = true;
	selphiWidget.previewImage = true;
	selphiWidget.timeout = 30000;
	selphiWidget.showLog = false;
	sdkProvider.appendChild(selphiWidget);

	//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>';
	}
	
	// Other events

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

This is only an approximation. It is possible to use different types of integration or syntax.

In this example, only the happy path, so the rest of the events also need to be integrated in real implementations.

---

Integration and configuration of component Flow

This example is an integration of the Happy Path for an Onboarding carried out using SelphID and Selphi.

First, with the instantiation of the SDK Provider, the internal logic will be triggered to initialize all services (loading, licensing, Initialization of Tracking, etc.).

When the Provider emits the event emitData, the first Widget (SelphID) will be loaded through the logic of initSelphidWidget(sdkProvider).

Once the user has completed the capture process, the SelphID Widget will close while emitting the event extractionFinish. In this event, the data will be processed as needed and the next component (Selphi) will be loaded with the method initSelphiWidget(sdkProvider);.

Finally, when the user finishes extracting the facial pattern, the obtained data will be processed as needed and the Flow will end, continuing with whatever logic is desired.

Flow between components

In more complete environments, such as current frameworks, it is possible to use components, routers, stores, and all kinds of tools to carry out that Flow.

The Facephi team recommends using components and routers for a more modular, simple, and faster integration in whichever framework you choose.

---

Behavior testing

Once the integration is complete, it is highly recommended to test in the application's development environment that the behavior is as expected, taking into account the possible configurations and cases that may appear in the Flow of end users.

---