For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migration guide

Step-by-step guide for migrating from previous versions to the latest versions of SDK Web.

SDK Web 3 - Main improvements and changes

Previous versions of SDK Web 2.x, Selphi Widgets 5.x and SelphID 4.x are considered deprecated and will not have the latest features implemented since their end-of-life date.

Why update to version 3.x

  • Performance: Resources are served from CDN, with usually faster and more stable access.

  • New features: The latest versions of SDK Web include all the new features developed so far.

  • Performance: The library components use modern technologies to maximize performance and ensure a smooth and efficient user experience.

  • Customization: The Customization of the components is now more complete and simpler.

  • Accessibility: The components of SDK Web 3 are natively accessible.

  • Less maintenance: there is no need to unzip or host local bundles as in older integrations.

  • Modular implementation: a single package @facephi/sdk-web-wc, components under <facephi-sdk-provider> and unified documentation.

  • Up-to-date product: improvements and new features are concentrated in the 3.x line of SDK Web (and in the current product line of widgets packaged in the SDK in their latest versions).

  • Frameworks: there are native wrappers for React and Angular (@facephi/sdk-web-react, @facephi/sdk-web-angular). More information in the section on Frameworks and Samples.

Following the steps described in this guide, migration to SDK Web 3.x can be completed and you can enjoy the improvements offered in the latest versions.

After any migration, it is advisable to do a test run in the target browsers and check that there are no broken references to paths or workers from the old package to ensure that the functionality remains operational.


Main changes

Topic
Before
In SDK Web 3

Resources

bundlePath and mandatory resource folders (SDK 2 or widgets .tgz)

Default loading from CDN; bundlePath Unnecessary

Implementation

Manual, required resource updates, unstable

Unified, streamlined, and stable implementation.

License

Individual licensing per product

Centralized use with apiKey in the SDK Provider (provided by Facephi)

Visual Customization

Limited and distributed according to widget/package

System of CSS variables in facephi-sdk-provider; customizable text via json; customizable resources (logo, loadingAnimation, tutorialAnimations)

Browser preloading methods

Only available in SelphID 4.x

Methods generateSelphiBrowserCache and generateSelphIDBrowserCache in the SDK Provider


Advantages of using the CDN

  • Simpler Integration.

  • Less infrastructure maintenance for SDK resources.

  • Automatic updates of the resources served from the CDN.

Things to keep in mind with the CDN

Content Security Policy (CSP)

If the application uses headers CSP strict, it is necessary to explicitly allow the SDK domains and associated resources (scripts, workers, API connections). Without this, the SDK may fail to load resources and produce runtime errors.

See the section Content Security Policy (CSP) in Additional configuration.


Migration from SDK Web 2 to SDK Web 3

Migration guide from SDK Web 2.x to SDK Web 3.x versions.

This guide summarizes the relevant changes in version 3.x of SDK Web and the recommended steps to migrate from versions of the line SDK Web 2.x to the latest versions of SDK Web 3.x.

Origin: already uses @facephi/sdk-web-wc in 2.x with the same unified family of web components.

Step-by-step guide for the update

  1. Remove bundlePath and delete resource folders that only served 2.x. The latest versions already package what is needed and use CDN by default.

  2. Update package.json to the latest version of @facephi/sdk-web-wc and install dependencies (fixed versions or latest according to your policy).

  3. Styles: the old customization is not fully compatible; adapt it to CSS variables and provider properties (see the table in the previous section).

  4. Licenses: configure the apiKey in <facephi-sdk-provider> according to what was received from Facephi.

  5. Review configuration of the provider and each widget against the current component documentation (renamed, obsolete, or newly ranged properties).

  6. CSP and end-to-end tests as in the first section.

The product “type” does not change (it remains the unified SDK Web), only the major version and the resource/license model.


Migration from Legacy Widgets to SDK Web 3

Migration guide from Legacy Widgets (Selphi 5.x and SelphID 4.x) to SDK Web 3.x.

SDK Web 3.x uses the latest versions of Selphi and SelphID in their 6.x versions, taking advantage of all the improvements they offer.

legacy integrations: packages independent (facephi-selphi-widget-web-*.tgz, facephi-selphid-widget-web-*.tgz), FPhi.Resources.Bundle.zip, scripts such as selphi-widget-web.min.js / selphid-widget-web.min.js and tags <facephi-selphi> and <facephi-selphid>.

In this process it is necessary to remove the legacy products and replace the entire Facephi layer with a single SDK Web 3.x Integration.

Breaking changes between Legacy and SDK Web 3

Comparison against the documentation of the web widgets legacy (@facephi/selphi-widget-web, @facephi/selphid-widget-web, guide API Reference) and the current versions of SDK Web (@facephi/sdk-web-wc).

We recommend consulting the documentation for each section for more information about any of the elements mentioned below.

Implementation

The most important changes regarding the Legacy versions compared to the latest versions of SDK Web.

  • Imperative API and utilities (FPhi.SelphID.* and FPhi.Selphi.*): deprecated as an integration reference. The legacy zip should no longer be taken as the source of truth for static methods or global constants FPhi.

  • The current engine is consumed as an npm library (@facephi/selphid-web-component / @facephi/selphi-web-component). The types and enums (ExpectedSides, DocumentType, extraction events, etc.) are imported from those packages.

  • Widget tags (<facephi-selphid> | <facephi-selphi>): renamed. Instead, <facephi-selphid-widget> and <facephi-selphi-widget> and will remain inside the tag <facephi-sdk-provider>.

  • The events of the SDK Web components are emitted in camelCase without prefix on (moduleLoaded, extractionFinish, …).

Several properties have a recommended new name. The previous name remains the main and operational one, but it is deprecated and will be removed in the next major version. If you define both, the new one wins and a precedence warning is issued in the console.

Selphi and SelphID:

  • initialTip: preferred showPreviousTip.

  • disableTutorial: preferred showTutorial (inverse logic).

  • disableExit: preferred showExitButton (inverse logic).

  • previewImage: preferred showResultAfterCapture.

  • cameraType: preferred cameraPreferred (text enum CameraPreferred: Front/Back).

Only Selphi:

  • livenessMoveSteps: preferred moveSuccessfulAttempts.

  • livenessMoveFailedAttempts: preferred moveFailedAttempts.

  • New livenessMode (enum LivenessMode) to select the liveness check mode.

Only SelphID:

  • chooseDocument: preferred showDocumentSelector.

  • countryFilter: preferred enabledCountries.

Selphi Widget

Breaking changes associated with Selphi compared to the latest versions of SDK Web.

Properties

  • bundlePath: deprecated. Now resource download and referencing is done internally automatically.

  • videoQuality: renamed to videoRecordQuality (typed as VideoRecordQuality).

  • tutorial: updated to showTutorial (inverse logic with respect to “show tutorial”; replaces disableTutorial).

  • previewCapture: renamed to showResultAfterCapture (formerly previewImage).

  • debugMode: renamed to debug.

  • language: deprecated. Languages are managed with the property language of the SDK Provider.

  • antispoofEnabled: renamed to antispoof.

  • stabilizationStage: renamed to stabilization.

  • cameraSwitchButton: renamed to cameraSwitch.

  • dpiList: deprecated.

  • resourcesPath: deprecated.

  • bundlePathExternal: deprecated.

  • preloadingMessage: deprecated.

  • accessibility: deprecated.

  • accessibleElements: deprecated.

  • graphPath: deprecated.

  • ephemeralKey: deprecated.

  • videoRecordScale: deprecated.

  • livenessMode: available from SDK Web 3.38 onwards with the enum LivenessMode (None/Move/Passive; in earlier versions it is not supported. See livenessMode and the section Recommended property names.

  • livenessPrecision: deprecated.

  • livenessMoveInitialError: deprecated.

  • livenessMoveInfoTime: deprecated.

  • authenticateTime: deprecated.

  • minLogImages: deprecated.

  • cropImage: deprecated.

Events

  • onModuleLoaded: renamed. In the wrapper host: moduleLoaded.

  • onTimeoutButtonClick: renamed to timeoutErrorButtonClick.

  • onStabilizing: renamed to stabilizing.

Methods

  • checkCapabilities(): deprecated. This functionality has been replaced by the subpath @facephi/sdk-web-wc/capabilities.mjs of the SDK Web library, callable before mounting the SDK Provider. Widgets also expose it in their own subpath /capabilities.mjs.

  • mountExternalCamera(): deprecated. This functionality has been replaced by the use of the property externalCamera in the Selphi and SelphID wrappers of SDK Web.

  • generateTemplateRawFromByteArray(): deprecated. This functionality is implemented internally in the latest versions of the components.

SelphID Widget

Breaking changes associated with SelphID compared to the latest versions of SDK Web.

Properties

  • licenseKey: deprecated. Now the license is managed internally through the SDK Provider apikey.

  • bundlePath: deprecated. Now resource download and referencing is done internally automatically.

  • tokenizer: renamed. The wrapper prop is tokenize (boolean to the engine).

  • specificdata: renamed to enabledCountries (formerly countryFilter).

  • documentMode: renamed to expectedSides (typed as ExpectedSides).

  • cameraSelection: renamed to cameraSwitch.

  • retryOnlyCurrentSide: renamed to retryCurrentSide.

  • videoQuality: renamed to videoRecordQuality (typed as VideoRecordQuality).

  • tutorial: updated to showTutorial (inverse logic with respect to “show tutorial”; replaces disableTutorial).

  • previewCapture: renamed to showResultAfterCapture (formerly previewImage).

  • allowUnknownDocuments: renamed to allowUnknown.

  • debugMode: renamed to debug.

  • documentType: updated. The wrapper supports DocumentType, arrays, and strings.

  • language: deprecated. Languages are managed with the property language of the SDK Provider.

  • askSimpleMode: deprecated. This functionality can be replaced by using the component File Uploader.

  • preloadingMessage: deprecated.

  • dpiList: updated to dpi.

  • resourcesPath: deprecated.

  • accessibility: deprecated.

  • accessibleElements: deprecated.

  • graphPath: deprecated.

  • ephemeralKey: deprecated.

  • videoRecordScale: deprecated.

  • mode: deprecated.

  • forceLandscape: deprecated.

  • canvasHD: deprecated.

  • startSimpleMode: deprecated.

  • cameraMirror: deprecated.

  • scanMode: deprecated.

  • documentAspectRatio: deprecated.

Events

  • onModuleLoaded: renamed. In the wrapper host: moduleLoaded.

  • onExtractionFinished: renamed to extractionFinish.

  • onUserCancelled: renamed to userCancel.

  • onTimeoutButtonClick: renamed to timeoutErrorButtonClick.

Methods

  • checkCapabilities(): deprecated. This functionality has been replaced by the subpath @facephi/sdk-web-wc/capabilities.mjs of the SDK Web library, callable before mounting the SDK Provider. Widgets also expose it in their own subpath /capabilities.mjs.

  • mountExternalCamera(): deprecated. This functionality has been replaced by the use of the property externalCamera in the Selphi and SelphID wrappers of SDK Web.

  • generateBrowserCache(): deprecated. Now it is the SDK Web library that provides the methods generateSelphiBrowserCache() and generateSelphIDBrowserCache().


Step-by-step guide for migration

  1. Uninstall legacy widgets and delete possible tgz files and ZIP files, standalone scripts, and resource folders used only by those widgets.

    1. Uninstall legacy libraries:

    2. Delete legacy files (TGZ files, ZIP files, scripts...):

    3. Delete resource folders with their contents:

  2. Install @facephi/sdk-web-wc 3.x and integrate <facephi-sdk-provider> as indicated in the installation guide.

    1. Add SDK Web 3 dependency:

    2. Prepare credentials file .npmrc with the required data:

    3. Install the library:

  3. Instantiation of <facephi-sdk-provider>, replace legacy tags with <facephi-selphi-widget> and <facephi-selphid-widget> (names, properties, and events different from those in 5.x / 4.x) and business flow restoration as indicated in the section Getting Started.

    1. Define the library custom elements in the project's main file:

    2. Instantiation of SDK Provider and its configuration:

      Warning: The components must be inside the tag facephi-sdk-provider and use the correct component labeling:

      • SelphID: It now uses the tag facelphi-selphid-widget.

      • Selphi: It now uses the tag facelphi-selphi-widget.

    3. Restore/implement Flow between components:

      This example uses JavaScript for navigation between components as shown.

      Facephi recommends using more advanced and scalable systems, such as TypeScript, frameworks, routers... Each implementation may differ in the method or element to load.

  4. Resolve breaking changes: Update the properties and events that require changes to reference or value, as well as remove deprecated elements. For this, we provide a guide to reference with updated, renamed, or deprecated elements in this documentation.

    1. Update the functionality of the new components to recover the desired behavior.

    2. If you previously had a custom design, it must be integrated with the new design system. For this process, you can consult the SDK Web Customization guide.

    3. Finally, all that remains is to carry out a series of tests on the devices deemed necessary to ensure that the operation is correct and meets the required criteria.

Business Flow: the order of steps (for example Selphi → SelphID → backend), JavaScript orchestration, the routers of SPA and the application's state can be maintained; only the Facephi capture within SDK Web 3 with the possible changes in the new components.

Last updated