> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/guia-de-migracion.md). # Migration guide ## 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 **``** 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](/docs.facephi-en/sdks/sdk-web/frameworks-y-samples.md#wrappers-espec-c3-adficos-de-framework). 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
TopicBeforeIn SDK Web 3
ResourcesbundlePath and required resource folders (SDK 2 or widgets .tgz)Default load from CDN; bundlePath Unnecessary
ImplementationManual, required updating resources, unstableUnified, summarized, and stable implementation.
LicenseIndividual licensing per productCentralized use with apiKey in the SDK Provider (facilitated by Facephi)
Visual customizationLimited and distributed according to widget/packageSystem of CSS variables in facephi-sdk-provider; customizable text through json; customizable resources (logo, loadingAnimation, tutorialAnimations)
Browser preload methodsOnly available in SelphID 4.xMethods 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)](/docs.facephi-en/sdks/sdk-web/introduccion/configuracion-adicional.md#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** 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** from `@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 to CSS variables and provider properties (see the table in the previous section). 4. **Licenses**: configure the **`apiKey`** in **``** as received from Facephi. 5. **Review configuration** of the provider and each widget against the current component documentation (renamed, deprecated, 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 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 **``** and **``**. 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. * [SDK Provider documentation](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider.md). * [SelphID Widget documentation](/docs.facephi-en/sdks/sdk-web/componentes/selphid-documentos.md). * [Selphi Widget documentation](/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial.md). #### 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 (`` | ``): **renamed**. Instead, `` and `` and will remain within the tag ``. * **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`. #### Selphi Widget 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`](/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial/propiedades/livenessmode.md) and the section [Recommended property names](#nombres-de-propiedad-recomendados-desde-sdk-web-338). * `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. #### 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 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](/docs.facephi-en/sdks/sdk-web/componentes/file-uploader-cargador-de-archivos.md). * `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** 1. **Uninstall** legacy widgets and **delete** possible tgz files and ZIP archives, loose scripts and resource folders used only by those widgets. 1. 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
          ...
      }
2. Remove legacy files (TGZ files, ZIP files, scripts...): 
facephi-selphid-widget-web-*.tgz  <- Eliminar
      facephi-selphi-widget-web-*.tgz  <- Eliminar
3. Remove resource folders along with their contents: 
assets/
          selphi/  <- Eliminar
          selphid/  <- Eliminar
2. **Install** `@facephi/sdk-web-wc` **3.x** and integrate **``** as indicated in the [installation guide](/docs.facephi-en/sdks/sdk-web/introduccion/instalacion.md). 1. Add SDK Web 3 dependency: 
// package.json
      ...
      "dependencies": {
          "@facephi/sdk-web-wc": "latest",
          ...
      }
2. 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 ``` 3. Install the library: ```bash npm install ``` 3. **Instantiation** from **``, replace legacy tags** by **``** and **``** (names, properties, and events different from those in 5.x / 4.x) and restore the business Flow as indicated in the section [Getting Started](/docs.facephi-en/sdks/sdk-web/introduccion/primeros-pasos.md). 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: ```jsx ``` > **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. 4. **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](#breaking-changes-entre-legacy-y-sdk-web-3) 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](/docs.facephi-en/sdks/sdk-web/personalizacion.md). 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.