> 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/sdks/sdk-web/guia-de-migracion.md). # Guía de migración ## SDK Web 3 - Mejoras y cambios principales Las versiones previas de **SDK Web 2.x, Widgets Selphi 5.x y SelphID 4.x se consideran deprecadas** y no dispondrán de las últimas funcionalidades implementadas desde su fecha de fin de vida. ### Por qué actualizar a la versión 3.x * **Rendimiento**: Los recursos se sirven desde **CDN**, con acceso habitualmente más rápido y estable. * **Nuevas funcionalidades**: Las últimas versiones del SDK Web cuenta con todas las nuevas funcionalidades desarrolladas hasta el momento. * **Rendimiento:** Los componentes de la librería utilizan tecnologías modernas para maximizar el rendimiento y garantizar una experiencia de usuario fluida y eficiente. * **Personalización:** La personalización de los componentes ahora es más completa y sencilla. * **Accesibilidad:** Los componentes del SDK Web 3 son accesibles de manera nativa. * **Menos mantenimiento**: no hace falta descomprimir ni alojar bundles locales como en integraciones antiguas. * **Implementación modular**: un único paquete **`@facephi/sdk-web-wc`**, componentes bajo **``** y documentación unificada. * **Producto al día**: mejoras y novedades se concentran en la **línea 3.x** del SDK Web (y en la línea de producto actual de widgets empaquetados en el SDK en sus últimas versiones). * **Frameworks**: existen wrappers nativos para **React** y **Angular** (`@facephi/sdk-web-react`, `@facephi/sdk-web-angular`). Más información en la sección de [Frameworks y Samples](/sdks/sdk-web/frameworks-y-samples.md#wrappers-espec-c3-adficos-de-framework). Siguiendo los pasos que se describen en esta guía se puede completar la migración a SDK Web 3.x y disfrutar de las mejoras que se ofrecen en las últimas versiones. Tras cualquier migración, conviene una **pasada de pruebas** en los navegadores objetivo y comprobar que no queden referencias rotas a rutas o workers del paquete antiguo para asegurar que la funcionalidad se mantiene operativa. *** ### Cambios principales
TemaAntesEn SDK Web 3
RecursosbundlePath y carpetas de recursos obligatorias (SDK 2 o widgets .tgz)Carga por defecto desde CDN; bundlePath Innecesario
ImplementaciónManual, requería actualizar recursos, inestableImplementación unificada, resumida y estable.
LicenciaLicenciamiento individual por productoUso centralizado con apiKey en el SDK Provider (facilitada por Facephi)
Personalización visualLimitada y repartida según widget/paqueteSistema de variables CSS en facephi-sdk-provider; textos personalizables a través de json; recursos personalizables (logo, loadingAnimation, tutorialAnimations)
Métodos de precarga en el navegadorSólo disponible en SelphID 4.xMétodos generateSelphiBrowserCache y generateSelphIDBrowserCache en el SDK Provider
*** ### Ventajas del uso del CDN * Integración más simple. * Menos mantenimiento de infraestructura para los recursos del SDK. * Actualizaciones automáticas de los recursos servidos desde el CDN. #### Aspectos a tener en cuenta con la CDN **Política de seguridad de contenido (CSP)** Si la aplicación usa cabeceras **CSP** estrictas, hay que **permitir explícitamente los dominios del SDK y los recursos asociados** (scripts, workers, conexiones API). Sin ello, el SDK puede no cargar recursos y producir errores en tiempo de ejecución. Consulta la sección [Content Security Policy (CSP)](/sdks/sdk-web/introduccion/configuracion-adicional.md#content-security-policy-csp) en Configuración adicional. *** ## Migración de SDK Web 2 a SDK Web 3 Guía de migración de versiones SDK Web 2.x a SDK Web 3.x. Esta guía resume los cambios relevantes de la versión **3.x** del SDK Web y los pasos recomendados para migrar desde versiones de la línea **SDK Web 2.x** hacia las **últimas versiones de SDK Web 3.x**. **Origen:** ya usa **`@facephi/sdk-web-wc` en 2.x** con la misma familia de web components unificada. ### **Guía paso a paso para la actualización** 1. **Quitar `bundlePath` y eliminar carpetas de recursos** que solo servían al 2.x. Las últimas versiones ya empaquetan lo necesario y usa CDN por defecto. 2. **Actualizar `package.json`** a la última **versión** de `@facephi/sdk-web-wc` e instalar dependencias (versiones fijas o `latest` según su política). 3. **Estilos**: la personalización antigua no es plenamente compatible; adapte a variables CSS y propiedades del provider (véase la tabla de la sección anterior). 4. **Licencias**: configure la **`apiKey`** en **``** según lo recibido de Facephi. 5. **Revisar configuración** del provider y de cada widget frente a la documentación actual de componentes (propiedades renombradas, obsoletas o con nuevos rangos). 6. **CSP** y **pruebas end-to-end** como en la primera sección. No cambia el “tipo” de producto (sigue siendo el SDK Web unificado), solo la **versión mayor** y el modelo de recursos/licencia. *** ## Migración de Widgets Legacy a SDK Web 3 Guía de migración de Widgets Legacy (Selphi 5.x y SelphID 4.x) a SDK Web 3.x. SDK Web 3.x usa las últimas versiones de Selphi y SelphID en sus versiones 6.x, aprovechando todas las mejoras que ofrecen. **integraciones legacy:** paquetes **independientes** (`facephi-selphi-widget-web-*.tgz`, `facephi-selphid-widget-web-*.tgz`), **`FPhi.Resources.Bundle.zip`**, scripts tipo **`selphi-widget-web.min.js`** / **`selphid-widget-web.min.js`** y etiquetas **``** y **``**. En este proceso es necesario **retirar los productos legacy** y **sustituir toda la capa Facephi** por una sola integración SDK Web 3.x. ### Breaking changes entre Legacy y SDK Web 3 Comparativa frente a la documentación de los widgets web **legacy** (`@facephi/selphi-widget-web`, `@facephi/selphid-widget-web`, guía *Referencia de la API*) y las versiones actuales del SDK Web (`@facephi/sdk-web-wc`). Recomendamos consultar la documentación de cada apartado para mayor información sobre cualquiera de los elementos mencionados a continuación. * [Documentación del SDK Provider](/sdks/sdk-web/componentes/sdk-provider.md). * [Documentación de SelphID Widget](/sdks/sdk-web/componentes/selphid-documentos.md). * [Documentación de Selphi Widget](/sdks/sdk-web/componentes/selphi-biometria-facial.md). #### Implementación Cambios más importantes referente a las versiones Legacy con respecto a las últimas versiones del SDK Web. * API imperativa y utilidades (`FPhi.SelphID.*` y `FPhi.Selphi.*`): **deprecado** como referencia de integración. Ya no se debe tomar el zip legacy como fuente de verdad para métodos estáticos o constantes globales `FPhi`. * El motor actual se consume como librería npm (`@facephi/selphid-web-component` / `@facephi/selphi-web-component`). Los tipos y enums (`ExpectedSides`, `DocumentType`, eventos de extracción, etc.) se importan desde esos paquetes. * Etiquetas de los widgets (`` | ``): **renombradas**. En su lugar se utilizará `` y `` y permanecerán dentro de la etiqueta ``. * **Los eventos de los componentes del SDK Web** se emiten en **camelCase** sin prefijo `on` (`moduleLoaded`, `extractionFinish`, …). #### Nombres de propiedad recomendados (desde SDK Web 3.38) Varias propiedades tienen un **nombre nuevo recomendado**. El nombre anterior sigue siendo la página principal y operativo, pero queda deprecado y **se retirará en la próxima versión major**. Si defines ambos, gana el nuevo y se emite un aviso de precedencia en consola. Selphi y SelphID: * `initialTip`: **preferido** `showPreviousTip`. * `disableTutorial`: **preferido** `showTutorial` (lógica inversa). * `disableExit`: **preferido** `showExitButton` (lógica inversa). * `previewImage`: **preferido** `showResultAfterCapture`. * `cameraType`: **preferido** `cameraPreferred` (enum de texto `CameraPreferred`: `Front`/`Back`). Solo Selphi: * `livenessMoveSteps`: **preferido** `moveSuccessfulAttempts`. * `livenessMoveFailedAttempts`: **preferido** `moveFailedAttempts`. * Nuevo `livenessMode` (enum `LivenessMode`) para seleccionar el modo de prueba de vida. Solo SelphID: * `chooseDocument`: **preferido** `showDocumentSelector`. * `countryFilter`: **preferido** `enabledCountries`. #### Selphi Widget Breaking changes asociados a Selphi con respecto a las últimas versiones de SDK Web. **Propiedades** * `bundlePath`: **deprecado**. Ahora la descarga y referencia de los recursos se hace internamente de manera automática. * `videoQuality`: **renombrado** a `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **actualizado** a `showTutorial` (lógica inversa respecto a “mostrar tutorial”; sustituye a `disableTutorial`). * `previewCapture`: **renombrado** a `showResultAfterCapture` (anteriormente `previewImage`). * `debugMode`: **renombrado** a `debug`. * `language`: **deprecado**. Los idiomas se gestionan con la propiedad `language` del SDK Provider. * `antispoofEnabled`: **renombrado** a `antispoof`. * `stabilizationStage`: **renombrado** a `stabilization`. * `cameraSwitchButton`: **renombrado** a `cameraSwitch`. * `dpiList`: **deprecado**. * `resourcesPath`: **deprecado**. * `bundlePathExternal`: **deprecado**. * `preloadingMessage`: **deprecado**. * `accessibility`: **deprecado**. * `accessibleElements`: **deprecado**. * `graphPath`: **deprecado**. * `ephemeralKey`: **deprecado**. * `videoRecordScale`: **deprecado**. * `livenessMode`: **disponible a partir de SDK Web 3.38** con el enum `LivenessMode` (`None`/`Move`/`Passive`); en versiones anteriores no está soportado. Ver [`livenessMode`](/sdks/sdk-web/componentes/selphi-biometria-facial/propiedades/livenessmode.md) y el apartado [Nombres de propiedad recomendados](#nombres-de-propiedad-recomendados-desde-sdk-web-338). * `livenessPrecision`: **deprecado**. * `livenessMoveInitialError`: **deprecado**. * `livenessMoveInfoTime`: **deprecado**. * `authenticateTime`: **deprecado**. * `minLogImages`: **deprecado**. * `cropImage`: **deprecado**. **Eventos** * `onModuleLoaded`: **renombrado**. En el host del wrapper: `moduleLoaded`. * `onTimeoutButtonClick`: **renombrado** a `timeoutErrorButtonClick`. * `onStabilizing`: **renombrado** a `stabilizing`. **Métodos** * `checkCapabilities()`: **deprecado**. Esta funcionalidad viene implementada internamente en las últimas versiones de los componentes. * `mountExternalCamera()`: **deprecado**. Esta funcionalidad ha sido reemplazada por el uso de la propiedad `externalCamera` en los wrappers Selphi y SelphID del SDK Web. * `generateTemplateRawFromByteArray()`: **deprecado**. Esta funcionalidad viene implementada internamente en las últimas versiones de los componentes. #### SelphID Widget Breaking changes asociados a SelphID con respecto a las últimas versiones de SDK Web. **Propiedades** * `licenseKey`: **deprecado**. Ahora la licencia se gestiona internamente mediante la apikey del SDK Provider. * `bundlePath`: **deprecado**. Ahora la descarga y referencia de los recursos se hace internamente de manera automática. * `tokenizer`: **renombrado**. La prop del wrapper es `tokenize` (boolean hacia el motor). * `specificdata`: **renombrado** a `enabledCountries` (anteriormente `countryFilter`). * `documentMode`: **renombrado** a `expectedSides` (tipado como `ExpectedSides`). * `cameraSelection`: **renombrado** a `cameraSwitch`. * `retryOnlyCurrentSide`: **renombrado** a `retryCurrentSide`. * `videoQuality`: **renombrado** a `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **actualizado** a `showTutorial` (lógica inversa respecto a “mostrar tutorial”; sustituye a `disableTutorial`). * `previewCapture`: **renombrado** a `showResultAfterCapture` (anteriormente `previewImage`). * `allowUnknownDocuments`: **renombrado** a `allowUnknown`. * `debugMode`: **renombrado** a `debug`. * `documentType`: **actualizado**. El wrapper admite `DocumentType`, arrays y strings. * `language`: **deprecado**. Los idiomas se gestionan con la propiedad `language` del SDK Provider. * `askSimpleMode`: **deprecado**. Esta funcionalidad puede ser sustituida por el uso del componente [File Uploader](/sdks/sdk-web/componentes/file-uploader-cargador-de-archivos.md). * `preloadingMessage`: **deprecado**. * `dpiList`: **actualizado** a `dpi`. * `resourcesPath`: **deprecado**. * `accessibility`: **deprecado**. * `accessibleElements`: **deprecado**. * `graphPath`: **deprecado**. * `ephemeralKey`: **deprecado**. * `videoRecordScale`: **deprecado**. * `mode`: **deprecado**. * `forceLandscape`: **deprecado**. * `canvasHD`: **deprecado**. * `startSimpleMode`: **deprecado**. * `cameraMirror`: **deprecado**. * `scanMode`: **deprecado**. * `documentAspectRatio`: **deprecado**. **Eventos** * `onModuleLoaded`: **renombrado**. En el host del wrapper: `moduleLoaded`. * `onExtractionFinished`: **renombrado** a `extractionFinish`. * `onUserCancelled`: **renombrado** a `userCancel`. * `onTimeoutButtonClick`: **renombrado** a `timeoutErrorButtonClick`. **Métodos** * `checkCapabilities()`: **deprecado**. Esta funcionalidad viene implementada internamente en las últimas versiones de los componentes. * `mountExternalCamera()`: **deprecado**. Esta funcionalidad ha sido reemplazada por el uso de la propiedad `externalCamera` en los wrappers Selphi y SelphID del SDK Web. * `generateBrowserCache()`: **deprecado**. Ahora es la librería SDK Web quien ofrece los métodos `generateSelphiBrowserCache()` y `generateSelphIDBrowserCache()`. *** ### **Guía paso a paso para la migración** 1. **Desinstalar** widgets legacy y **eliminar** posibles ficheros tgz y archivos ZIP, scripts sueltos y carpetas de recursos usadas solo por esos widgets. 1. Desinstalar librerías legacy: 
// 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. Eliminar archivos legacy (ficheros TGZ, ZIP, scripts...): 
facephi-selphid-widget-web-*.tgz  <- Eliminar
      facephi-selphi-widget-web-*.tgz  <- Eliminar
3. Eliminar carpetas de recursos con su contenido: 
assets/
          selphi/  <- Eliminar
          selphid/  <- Eliminar
2. **Instalar** `@facephi/sdk-web-wc` **3.x** e integrar **``** como se indica en la [guía de instalación](/sdks/sdk-web/introduccion/instalacion.md). 1. Añadir dependencia de SDK Web 3: 
// package.json
      ...
      "dependencies": {
          "@facephi/sdk-web-wc": "latest",
          ...
      }
2. Preparar archivo de credenciales `.npmrc` con los datos requeridos: ``` @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. Instalar la librería: ```bash npm install ``` 3. **Instanciación** de **``, sustituir etiquetas legacy** por **``** y **``** (nombres, propiedades y eventos distintos a los del 5.x / 4.x) y restauración de flujo de negocio como se indica en la sección [Primeros Pasos](/sdks/sdk-web/introduccion/primeros-pasos.md). 1. Definir custom elements de la librería en el archivo principal del proyecto: 
// main.js
      import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader';
      defineFacephiSdkCustomComponent(window);
2. Instanciación de SDK Provider y su configuración: ```jsx ``` > **Advertencia**: Los componentes deben estar **dentro** de la etiqueta **`facephi-sdk-provider`** y utilizar el correcto etiquetado de los componentes: > > * **SelphID**: Ahora utiliza la etiqueta `facelphi-selphid-widget`. > * **Selphi**: Ahora utiliza la etiqueta `facelphi-selphi-widget`. 3. Restaurar/implementar flujo entre componentes: 
function onSelphIDExtractionFinish(event) {
          const result = event.detail;
          console.log("[SELPHID] ExtractionFinish", result);
          // Cargar Selphi una vez SelphID haya finalizado la extracción
          initializeSelphiWidget();
      }
> Este ejemplo utiliza JavaScript para la navegación entre componentes como muestra. > > **Facephi recomienda** el uso de sistemas más avanzados y escalables, como typescript, frameworks, routers... Cada implementación puede diferenciar el método o elemento a cargar. 4. **Resolver breaking changes**: Actualizar las propiedades y eventos que requieran cambios de referencia o valor, así como eliminar los elementos deprecados.\ Para ello dejamos una guía de [referencia con los elementos actualizados, renombrados o deprecados](#breaking-changes-entre-legacy-y-sdk-web-3) en esta documentación. 1. Actualizar funcionalidad de los nuevos componentes para recuperar el funcionamiento deseado. 2. En caso de tener un diseño personalizado previo, es necesario integrarlo con el nuevo sistema de diseño. Para este proceso es posible consultar [la guía de personalización del SDK Web](/sdks/sdk-web/personalizacion.md). 3. Por último solo quedaría realizar una batería de pruebas en los dispositivos que se considere para asegurar que el funcionamiento es el correcto y cumple con los criterios necesarios.
**Flujo de negocio:** el orden de pasos (por ejemplo Selphi → SelphID → backend), la **orquestación en JavaScript**, los **routers** de SPA y el estado de la aplicación **pueden mantenerse**; solo debe reimplementarse la **captura Facephi** dentro del SDK Web 3 con los posibles cambios de los nuevos componentes.