> 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 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 **``** 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](/docs.facephi-en/sdks/sdk-web/frameworks-y-samples.md#wrappers-espec-c3-adficos-de-framework). 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
TopicBeforeIn SDK Web 3
ResourcesbundlePath and mandatory resource folders (SDK 2 or widgets .tgz)Default loading from CDN; bundlePath Unnecessary
ImplementationManual, required resource updates, unstableUnified, streamlined, and stable implementation.
LicenseIndividual licensing per productCentralized use with apiKey in the SDK Provider (provided by Facephi)
Visual CustomizationLimited and distributed according to widget/packageSystem of CSS variables in facephi-sdk-provider; customizable text via json; customizable resources (logo, loadingAnimation, tutorialAnimations)
Browser preloading methodsOnly available in SelphID 4.xMethods 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)](/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 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 **``** 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 **``** and **``**. 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. * [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 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 (`` | ``): **renamed**. Instead, `` and `` and will remain inside the tag ``. * **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`: **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`](/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: `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](/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: `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: 
// package.json
      ...
      "dependencies": {
          "@facephi/selphid-widget-web": "file:facephi-selphid-widget-web-*.tgz", <- Remove
          "@facephi/selphi-widget-web": "file:facephi-selphi-widget-web-*.tgz", <- Remove
          ...
      }
2. Delete legacy files (TGZ files, ZIP files, scripts...): 
facephi-selphid-widget-web-*.tgz  <- Remove
      facephi-selphi-widget-web-*.tgz  <- Remove
3. Delete resource folders with their contents: 
assets/
          selphi/  <- Remove
          selphid/  <- Remove
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 credentials file `.npmrc` with the required data: ``` @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=[USERNAME] //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** of **``, replace legacy tags** with **``** and **``** (names, properties, and events different from those in 5.x / 4.x) and business flow restoration as indicated in the section [Getting Started](/docs.facephi-en/sdks/sdk-web/introduccion/primeros-pasos.md). 1. Define the library custom elements in the project's main file: 
// main.js
      import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader';
      defineFacephiSdkCustomComponent(window);
2. Instantiation of SDK Provider and its configuration: ```jsx ``` > **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: 
function onSelphIDExtractionFinish(event) {
          const result = event.detail;
          console.log("[SELPHID] ExtractionFinish", result);
          // Load Selphi once SelphID has finished extraction
          initializeSelphiWidget();
      }
> 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](#breaking-changes-entre-legacy-y-sdk-web-3) 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](/docs.facephi-en/sdks/sdk-web/personalizacion.md). 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.