Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Guía de migración

Guía "paso a paso" de migración de versiones anteriores a últimas versiones de SDK Web.

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 <facephi-sdk-provider> 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.

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

Tema
Antes
En SDK Web 3

Recursos

bundlePath y carpetas de recursos obligatorias (SDK 2 o widgets .tgz)

Carga por defecto desde CDN; bundlePath Innecesario

Implementación

Manual, requería actualizar recursos, inestable

Implementación unificada, resumida y estable.

Licencia

Licenciamiento individual por producto

Uso centralizado con apiKey en el SDK Provider (facilitada por Facephi)

Personalización visual

Limitada y repartida según widget/paquete

Sistema 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 navegador

Sólo disponible en SelphID 4.x

Mé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) 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 <facephi-sdk-provider> 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 <facephi-selphi> y <facephi-selphid>.

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.

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 (<facephi-selphid> | <facephi-selphi>): renombradas. En su lugar se utilizará <facephi-selphid-widget> y <facephi-selphi-widget> y permanecerán dentro de la etiqueta <facephi-sdk-provider>.

  • 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 y el apartado Nombres de propiedad recomendados.

  • 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 ha sido reemplazada por el subpath @facephi/sdk-web-wc/capabilities.mjs de la librería SDK Web, invocable antes de montar el SDK Provider. Los widgets lo exponen también en su propio subpath /capabilities.mjs.

  • 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.

  • 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 ha sido reemplazada por el subpath @facephi/sdk-web-wc/capabilities.mjs de la librería SDK Web, invocable antes de montar el SDK Provider. Los widgets lo exponen también en su propio subpath /capabilities.mjs.

  • 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:

    2. Eliminar archivos legacy (ficheros TGZ, ZIP, scripts...):

    3. Eliminar carpetas de recursos con su contenido:

  2. Instalar @facephi/sdk-web-wc 3.x e integrar <facephi-sdk-provider> como se indica en la guía de instalación.

    1. Añadir dependencia de SDK Web 3:

    2. Preparar archivo de credenciales .npmrc con los datos requeridos:

    3. Instalar la librería:

  3. Instanciación de <facephi-sdk-provider>, sustituir etiquetas legacy por <facephi-selphi-widget> y <facephi-selphid-widget> (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.

    1. Definir custom elements de la librería en el archivo principal del proyecto:

    2. Instanciación de SDK Provider y su configuración:

      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:

      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 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.

    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.

AnteriorPreguntas y errores frecuentes
SiguienteChangeLog

Última actualización