Migration guide

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

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: Customization of the components is now more complete and simpler.
Accessibility: The SDK Web 3 components are natively accessible.
Less maintenance: 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: native wrappers exist for React and Angular (@facephi/sdk-web-react, @facephi/sdk-web-angular ). More information in the section on Frameworks and Samples.

By following the steps described in this guide, you can complete the migration to SDK Web 3.x and enjoy the improvements offered in the latest versions.

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

Main changes

Topic

Before

In SDK Web 3

Resources

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

Default load from CDN; bundlePath Unnecessary

Implementation

Manual, required updating resources, unstable

Unified, summarized, and stable implementation.

License

Individual licensing per product

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

Visual customization

Limited and distributed according to widget/package

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

Browser preload methods

Only available in SelphID 4.x

Methods generateSelphiBrowserCache and generateSelphIDBrowserCache in SDK Provider

Benefits of using the CDN

Simpler integration.
Less infrastructure maintenance for SDK resources.
Automatic updates of resources served from the CDN.

Points to keep in mind with the CDN

Content Security Policy (CSP)

If the application uses headers CSP strict, you must 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 versions to SDK Web 3.x.

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

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

Step-by-step guide for updating

Remove bundlePath and delete resource folders that only served 2.x. The latest versions already package what is needed and use CDN by default.
Update package.json to the latest version from @facephi/sdk-web-wc and install dependencies (fixed versions or latest according to your policy).
Styles: the old customization is not fully compatible; adapt to CSS variables and provider properties (see the table in the previous section).
Licenses: configure the apiKey in <facephi-sdk-provider> as received from Facephi.
Review configuration of the provider and each widget against the current component documentation (renamed, deprecated, 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 for 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 to replace the entire Facephi layer with a single SDK Web 3.x integration.

Breaking changes between Legacy and SDK Web 3

Comparison against the legacy web widgets documentation 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

Most important changes regarding 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). Types and enums (ExpectedSides, DocumentType, extraction events, etc.) are imported from those packages.
Widget labels (<facephi-selphid> | <facephi-selphi>): renamed. Instead, <facephi-selphid-widget> and <facephi-selphi-widget> and will remain within the tag <facephi-sdk-provider>.
Events of SDK Web components are emitted in camelCase without the on (prefix, extractionFinish, …).

Recommended property names (since SDK Web 3.38)

Several properties have a recommended new name. The old name is still the main page and operational, 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.

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

Properties

bundlePath: deprecated. Now the download and reference of resources 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 starting from SDK Web 3.38 with enum LivenessMode (None/Move/Passive); in previous 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: prefix.
onTimeoutButtonClick: renamed to timeoutErrorButtonClick.
onStabilizing: renamed to stabilizing.

Methods

checkCapabilities(): deprecated. This functionality is implemented internally in the latest versions of the components.
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.

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 the download and reference of resources 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: prefix.
onExtractionFinished: renamed to extractionFinish.
onUserCancelled: renamed to userCancel.
onTimeoutButtonClick: renamed to timeoutErrorButtonClick.

Methods

checkCapabilities(): deprecated. This functionality is implemented internally in the latest versions of the components.
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 the SDK Web library offers the methods generateSelphiBrowserCache() and generateSelphIDBrowserCache().

Step-by-step migration guide

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

Uninstall legacy libraries:

// package.json
...
"dependencies": {
    "@facephi/selphid-widget-web": "file:facephi-selphid-widget-web-*.tgz", <- Eliminar
    "@facephi/selphi-widget-web": "file:facephi-selphi-widget-web-*.tgz", <- Eliminar
    ...
}

Remove legacy files (TGZ files, ZIP files, scripts...):

facephi-selphid-widget-web-*.tgz  <- Eliminar
facephi-selphi-widget-web-*.tgz  <- Eliminar

Remove resource folders along with their contents:

assets/
    selphi/  <- Eliminar
    selphid/  <- Eliminar

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

Add SDK Web 3 dependency:

// package.json
...
"dependencies": {
    "@facephi/sdk-web-wc": "latest",
    ...
}

Prepare the credentials file .npmrc with the required details:

@facephi:registry=https://facephicorp.jfrog.io/artifactory/api/npm/sdk-web-fphi/
//facephicorp.jfrog.io/artifactory/api/npm/sdk-web-fphi/:_password=[TOKEN]
//facephicorp.jfrog.io/artifactory/api/npm/sdk-web-fphi/:username=[USUARIO]
//facephicorp.jfrog.io/artifactory/api/npm/sdk-web-fphi/:email=[EMAIL]
//facephicorp.jfrog.io/artifactory/api/npm/sdk-web-fphi/:always-auth=true

Install the library:
```
npm install
```

Instantiation from <facephi-sdk-provider>, replace legacy tags by <facephi-selphi-widget> and <facephi-selphid-widget> (names, properties, and events different from those in 5.x / 4.x) and restore the business Flow as indicated in the section Getting Started.
1. Define the library's custom elements in the project's main file:
  // main.js import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader'; defineFacephiSdkCustomComponent(window);
2. SDK Provider instantiation and configuration:
  <facephi-sdk-provider apikey={process.env.FACEPHI_SDK_APIKEY} customerId={uniqueCustomerId} > <facelphi-selphid-widget /> </facephi-sdk-provider>
  Warning: Components must be inside the tag facephi-sdk-provider and use the correct component markup:
  SelphID: It now uses the tag facelphi-selphid-widget.
  Selphi: It now uses the tag facelphi-selphi-widget.
3. Restore/implement Flow between components:
  function onSelphIDExtractionFinish(event) { const result = event.detail; console.log("[SELPHID] ExtractionFinish", result); // Cargar Selphi una vez SelphID haya finalizado la extracción initializeSelphiWidget(); }
  This example uses JavaScript for navigation between components, as shown.
  Facephi recommends the use of 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 reference or value changes, and remove deprecated elements. For this purpose, we provide a guide to reference with updated, renamed, or deprecated elements in this documentation.
1. Update the functionality of the new components to restore the desired behavior.
2. If you have a previous customized design, it is necessary to integrate it 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 set of tests on the devices deemed appropriate to ensure that the operation is correct and meets the necessary criteria.

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

PreviousFrequently asked questions and errors NextChangelog

Last updated 16 days ago