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
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
Remove
bundlePathand delete resource folders that only served 2.x. The latest versions already package what is needed and use CDN by default.Update
package.jsonto the latest version of@facephi/sdk-web-wcand install dependencies (fixed versions orlatestaccording to your policy).Styles: the old customization is not fully compatible; adapt it to CSS variables and provider properties (see the table in the previous section).
Licenses: configure the
apiKeyin<facephi-sdk-provider>according to what was received from Facephi.Review configuration of the provider and each widget against the current component documentation (renamed, obsolete, or newly ranged properties).
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.*andFPhi.Selphi.*): deprecated as an integration reference. The legacy zip should no longer be taken as the source of truth for static methods or global constantsFPhi.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, …).
Recommended property names (from SDK Web 3.38)
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: preferredshowPreviousTip.disableTutorial: preferredshowTutorial(inverse logic).disableExit: preferredshowExitButton(inverse logic).previewImage: preferredshowResultAfterCapture.cameraType: preferredcameraPreferred(text enumCameraPreferred:Front/Back).
Only Selphi:
livenessMoveSteps: preferredmoveSuccessfulAttempts.livenessMoveFailedAttempts: preferredmoveFailedAttempts.New
livenessMode(enumLivenessMode) to select the liveness check mode.
Only SelphID:
chooseDocument: preferredshowDocumentSelector.countryFilter: preferredenabledCountries.
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 tovideoRecordQuality(typed asVideoRecordQuality).tutorial: updated toshowTutorial(inverse logic with respect to “show tutorial”; replacesdisableTutorial).previewCapture: renamed toshowResultAfterCapture(formerlypreviewImage).debugMode: renamed todebug.language: deprecated. Languages are managed with the propertylanguageof the SDK Provider.antispoofEnabled: renamed toantispoof.stabilizationStage: renamed tostabilization.cameraSwitchButton: renamed tocameraSwitch.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 enumLivenessMode(None/Move/Passive; in earlier versions it is not supported. SeelivenessModeand 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 totimeoutErrorButtonClick.onStabilizing: renamed tostabilizing.
Methods
checkCapabilities(): deprecated. This functionality has been replaced by the subpath@facephi/sdk-web-wc/capabilities.mjsof 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 propertyexternalCamerain 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 istokenize(boolean to the engine).specificdata: renamed toenabledCountries(formerlycountryFilter).documentMode: renamed toexpectedSides(typed asExpectedSides).cameraSelection: renamed tocameraSwitch.retryOnlyCurrentSide: renamed toretryCurrentSide.videoQuality: renamed tovideoRecordQuality(typed asVideoRecordQuality).tutorial: updated toshowTutorial(inverse logic with respect to “show tutorial”; replacesdisableTutorial).previewCapture: renamed toshowResultAfterCapture(formerlypreviewImage).allowUnknownDocuments: renamed toallowUnknown.debugMode: renamed todebug.documentType: updated. The wrapper supportsDocumentType, arrays, and strings.language: deprecated. Languages are managed with the propertylanguageof the SDK Provider.askSimpleMode: deprecated. This functionality can be replaced by using the component File Uploader.preloadingMessage: deprecated.dpiList: updated todpi.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 toextractionFinish.onUserCancelled: renamed touserCancel.onTimeoutButtonClick: renamed totimeoutErrorButtonClick.
Methods
checkCapabilities(): deprecated. This functionality has been replaced by the subpath@facephi/sdk-web-wc/capabilities.mjsof 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 propertyexternalCamerain the Selphi and SelphID wrappers of SDK Web.generateBrowserCache(): deprecated. Now it is the SDK Web library that provides the methodsgenerateSelphiBrowserCache()andgenerateSelphIDBrowserCache().
Step-by-step guide for migration
Uninstall legacy widgets and delete possible tgz files and ZIP files, standalone scripts, and resource folders used only by those widgets.
Uninstall legacy libraries:
Delete legacy files (TGZ files, ZIP files, scripts...):
Delete resource folders with their contents:
Install
@facephi/sdk-web-wc3.x and integrate<facephi-sdk-provider>as indicated in the installation guide.Add SDK Web 3 dependency:
Prepare credentials file
.npmrcwith the required data:Install the library:
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.Define the library custom elements in the project's main file:
Instantiation of SDK Provider and its configuration:
Warning: The components must be inside the tag
facephi-sdk-providerand use the correct component labeling:SelphID: It now uses the tag
facelphi-selphid-widget.Selphi: It now uses the tag
facelphi-selphi-widget.
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.
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.
Update the functionality of the new components to recover the desired behavior.
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.
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