> 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:** Component customization is now more complete and easier. * **Accessibility:** SDK Web 3 components 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 of [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 is advisable to do a **round of tests** in the target browsers and verify that there are no broken references to paths or workers from the old package to ensure the 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 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 texts through 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 the SDK resources. * Automatic updates of the resources served from the CDN. #### Considerations for 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 for SDK Web 2.x to SDK Web 3.x versions. This guide summarizes the relevant changes of Version **3.x** of SDK Web and the recommended steps to migrate from versions of the line **SDK Web 2.x** towards 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 the update** 1. **Remove `bundlePath` and delete resource folders** that only served 2.x. The latest versions already package what is necessary 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**: 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 properties, deprecated properties, or properties with new ranges). 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 resources/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 on 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 with 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, the following will be used `` and `` and will remain within the tag ``. * **The events of the SDK Web components** are emitted in **camelCase** without the prefix `on` (`moduleLoaded`, `extractionFinish`, ...). #### Recommended property names (since SDK Web 3.38) Several properties have a **new recommended 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 takes precedence and a precedence warning is emitted 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`). Selphi only: * `livenessMoveSteps`: **preferred** `moveSuccessfulAttempts`. * `livenessMoveFailedAttempts`: **preferred** `moveFailedAttempts`. * New `livenessMode` (enum `LivenessMode`) to select the liveness check mode. SelphID only: * `chooseDocument`: **preferred** `showDocumentSelector`. * `countryFilter`: **preferred** `enabledCountries`. #### Selphi Widget Breaking changes associated with Selphi with respect to the latest versions of SDK Web. **Properties** * `bundlePath`: **deprecated**. Now the download and reference of the 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**. The 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 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: `moduleLoaded`. * `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 with respect to the latest versions of SDK Web. **Properties** * `licenseKey`: **deprecated**. Now the license is managed internally through the SDK Provider API key. * `bundlePath`: **deprecated**. Now the download and reference of the 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**. The languages are managed with the property `language` of the SDK Provider. * `askSimpleMode`: **deprecated**. This functionality can be replaced by the use of 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 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 it is the SDK Web library that offers the methods `generateSelphiBrowserCache()` and `generateSelphIDBrowserCache()`. *** ### **Step-by-step guide for the migration** 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", <- 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=[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 **``** (different names, properties and events other than those in 5.x / 4.x) and restoration of 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. Instantiation of the SDK Provider and its configuration: ```jsx ``` > **Warning**: The components must be **inside** the tag **`facephi-sdk-provider`** and use the correct component tags: > > * **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** 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, as well as remove deprecated elements.\ For this, we provide a reference guide [with the 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 custom 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, it would only remain to run a set of tests on the devices considered necessary to ensure that the operation is correct and meets the required criteria.
**Business Flow:** the order of steps (for example Selphi → SelphID → backend), the **orchestration in JavaScript**, the **routers** of SPA and the application state **can be maintained**; only the **Facephi capture** within SDK Web 3 with the possible changes of the new components.