> 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-pt-br/sdks/sdk-web/guia-de-migracion.md). # Guia de migração Guia "passo a passo" de migração de versões anteriores para as versões mais recentes do SDK Web. ## SDK Web 3 - Melhorias e mudanças principais As versões anteriores de **SDK Web 2.x, Widgets Selphi 5.x e SelphID 4.x são consideradas deprecadas** e não contarão com as últimas funcionalidades implementadas desde sua data de fim de vida. ### Por que atualizar para a versão 3.x * **Desempenho**: Os recursos são servidos a partir de **CDN**, com acesso normalmente mais rápido e estável. * **Novas funcionalidades**: As versões mais recentes do SDK Web contam com todas as novas funcionalidades desenvolvidas até o momento. * **Desempenho:** Os componentes da biblioteca usam tecnologias modernas para maximizar o desempenho e garantir uma experiência de usuário fluida e eficiente. * **Personalização:** A personalização dos componentes agora é mais completa e simples. * **Acessibilidade:** Os componentes do SDK Web 3 são acessíveis nativamente. * **Menos manutenção**: não é necessário descompactar nem hospedar bundles locais como em integrações antigas. * **Implementação modular**: um único pacote **`@facephi/sdk-web-wc`**, componentes sob **``** e documentação unificada. * **Produto atualizado**: melhorias e novidades se concentram na **linha 3.x** do SDK Web (e na linha de produto atual de widgets empacotados no SDK em suas versões mais recentes). * **Frameworks**: existem wrappers nativos para **React** e **Angular** (`@facephi/sdk-web-react`, `@facephi/sdk-web-angular`). Mais informações na seção de [Frameworks e Samples](/docs.facephi-pt-br/sdks/sdk-web/frameworks-y-samples.md#wrappers-espec-c3-adficos-de-framework). Seguindo os passos descritos neste guia, é possível concluir a migração para o SDK Web 3.x e aproveitar as melhorias oferecidas nas versões mais recentes. Após qualquer migração, convém uma **rodada de testes** nos navegadores-alvo e verificar que não restem referências quebradas a rotas ou workers do pacote antigo para assegurar que a funcionalidade permaneça operando. *** ### Principais mudanças
TemaAntesNo SDK Web 3
RecursosbundlePath e pastas de recursos obrigatórias (SDK 2 ou widgets .tgz)Carregamento padrão a partir de CDN; bundlePath Desnecessário
ImplementaçãoManual, exigia atualizar recursos, instávelImplementação unificada, resumida e estável.
LicençaLicenciamento individual por produtoUso centralizado com apiKey no SDK Provider (fornecida pela Facephi)
Personalização visualLimitada e distribuída conforme widget/pacoteSistema de variáveis CSS em facephi-sdk-provider; textos personalizáveis por meio de json; recursos personalizáveis (logo, loadingAnimation, tutorialAnimations)
Métodos de pré-carregamento no navegadorDisponível apenas em SelphID 4.xMétodos generateSelphiBrowserCache e generateSelphIDBrowserCache no SDK Provider
*** ### Vantagens do uso da CDN * Integração mais simples. * Menor manutenção de infraestrutura para os recursos do SDK. * Atualizações automáticas dos recursos servidos pela CDN. #### Aspectos a ter em conta com a CDN **Política de segurança de conteúdo (CSP)** Se a aplicação usa cabeçalhos **CSP** estritos, é preciso **permitir explicitamente os domínios do SDK e os recursos associados** (scripts, workers, conexões API). Sem isso, o SDK pode não carregar recursos e gerar erros em tempo de execução. Consulte a seção [Content Security Policy (CSP)](/docs.facephi-pt-br/sdks/sdk-web/introduccion/configuracion-adicional.md#content-security-policy-csp) em Configuração adicional. *** ## Migração de SDK Web 2 para SDK Web 3 Guia de migração de versões do SDK Web 2.x para SDK Web 3.x. Este guia resume as mudanças relevantes da versão **3.x** do SDK Web e os passos recomendados para migrar desde versões da linha **SDK Web 2.x** para as **últimas versões do SDK Web 3.x**. **Origem:** já usa **`@facephi/sdk-web-wc` em 2.x** com a mesma família unificada de web components. ### **Guia passo a passo para a atualização** 1. **Remover `bundlePath` e eliminar pastas de recursos** que serviam apenas ao 2.x. As últimas versões já empacotam o necessário e usam CDN por padrão. 2. **Atualizar `package.json`** para a última **versão** de `@facephi/sdk-web-wc` e instalar dependências (versões fixas ou `latest` conforme sua política). 3. **Estilos**: a personalização antiga não é plenamente compatível; adapte para variáveis CSS e propriedades do provider (veja a tabela da seção anterior). 4. **Licenças**: configure a **`apiKey`** em **``** conforme o recebido da Facephi. 5. **Revisar a configuração** do provider e de cada widget frente à documentação atual dos componentes (propriedades renomeadas, obsoletas ou com novos intervalos). 6. **CSP** e **testes end-to-end** como na primeira seção. Não muda o “tipo” de produto (continua sendo o SDK Web unificado), apenas a **versão major** e o modelo de recursos/licença. *** ## Migração de Widgets Legacy para SDK Web 3 Guia de migração de Widgets Legacy (Selphi 5.x e SelphID 4.x) para SDK Web 3.x. O SDK Web 3.x usa as versões mais recentes de Selphi e SelphID em suas versões 6.x, aproveitando todas as melhorias que oferecem. **integrações legadas:** pacotes **independentes** (`facephi-selphi-widget-web-*.tgz`, `facephi-selphid-widget-web-*.tgz`), **`FPhi.Resources.Bundle.zip`**, scripts do tipo **`selphi-widget-web.min.js`** / **`selphid-widget-web.min.js`** e etiquetas **``** e **``**. Neste processo é necessário **remover os produtos legados** e **substituir toda a camada Facephi** por uma única integração SDK Web 3.x. ### Mudanças incompatíveis entre Legacy e SDK Web 3 Comparação frente à documentação dos widgets web **legacy** (`@facephi/selphi-widget-web`, `@facephi/selphid-widget-web`, guia *Referência da API*) e as versões atuais do SDK Web (`@facephi/sdk-web-wc`). Recomendamos consultar a documentação de cada seção para obter mais informações sobre qualquer um dos elementos mencionados a seguir. * [Documentação do SDK Provider](/docs.facephi-pt-br/sdks/sdk-web/componentes/sdk-provider.md). * [Documentação do SelphID Widget](/docs.facephi-pt-br/sdks/sdk-web/componentes/selphid-documentos.md). * [Documentação do Selphi Widget](/docs.facephi-pt-br/sdks/sdk-web/componentes/selphi-biometria-facial.md). #### Implementação Mudanças mais importantes em relação às versões Legacy com respeito às versões mais recentes do SDK Web. * API imperativa e utilitários (`FPhi.SelphID.*` e `FPhi.Selphi.*`): **deprecado** como referência de integração. O zip legacy não deve mais ser tomado como fonte de verdade para métodos estáticos ou constantes globais `FPhi`. * O motor atual é consumido como biblioteca npm (`@facephi/selphid-web-component` / `@facephi/selphi-web-component`). Os tipos e enums (`ExpectedSides`, `DocumentType`, eventos de extração etc.) são importados desses pacotes. * Etiquetas dos widgets (`` | ``): **renomeadas**. Em seu lugar será usado `` e `` e permanecerão dentro da etiqueta ``. * **Os eventos dos componentes do SDK Web** são emitidos em **camelCase** sem prefixo `on` (`moduleLoaded`, `extractionFinish`, …). #### Nomes de propriedade recomendados (desde SDK Web 3.38) Várias propriedades têm um **novo nome recomendado**. O nome anterior continua sendo a página principal e operacional, mas fica deprecado e **será removido na próxima versão major**. Se você definir ambos, o novo prevalece e um aviso de precedência é emitido no console. Selphi e 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`). Apenas Selphi: * `livenessMoveSteps`: **preferido** `moveSuccessfulAttempts`. * `livenessMoveFailedAttempts`: **preferido** `moveFailedAttempts`. * Novo `livenessMode` (enum `LivenessMode`) para selecionar o modo de teste de vida. Apenas SelphID: * `chooseDocument`: **preferido** `showDocumentSelector`. * `countryFilter`: **preferido** `enabledCountries`. #### Selphi Widget Mudanças incompatíveis associadas ao Selphi em relação às versões mais recentes do SDK Web. **Propriedades** * `bundlePath`: **deprecado**. Agora o download e a referência dos recursos são feitos internamente de forma automática. * `videoQuality`: **renomeado** para `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **atualizado** para `showTutorial` (lógica inversa em relação a “mostrar tutorial”; substitui `disableTutorial`). * `previewCapture`: **renomeado** para `showResultAfterCapture` (anteriormente `previewImage`). * `debugMode`: **renomeado** para `Debug`. * `language`: **deprecado**. Os idiomas são gerenciados com a propriedade `language` do SDK Provider. * `antispoofEnabled`: **renomeado** para `antispoof`. * `stabilizationStage`: **renomeado** para `stabilization`. * `cameraSwitchButton`: **renomeado** para `cameraSwitch`. * `dpiList`: **deprecado**. * `resourcesPath`: **deprecado**. * `bundlePathExternal`: **deprecado**. * `preloadingMessage`: **deprecado**. * `acessibilidade`: **deprecado**. * `accessibleElements`: **deprecado**. * `graphPath`: **deprecado**. * `ephemeralKey`: **deprecado**. * `videoRecordScale`: **deprecado**. * `livenessMode`: **disponível a partir do SDK Web 3.38** com o enum `LivenessMode` (`None`/`Move`/`Passive`); em versões anteriores não é suportado. Veja [`livenessMode`](/docs.facephi-pt-br/sdks/sdk-web/componentes/selphi-biometria-facial/propiedades/livenessmode.md) e a seção [Nomes de propriedade recomendados](#nombres-de-propiedad-recomendados-desde-sdk-web-338). * `livenessPrecision`: **deprecado**. * `livenessMoveInitialError`: **deprecado**. * `livenessMoveInfoTime`: **deprecado**. * `authenticateTime`: **deprecado**. * `minLogImages`: **deprecado**. * `cropImage`: **deprecado**. **Eventos** * `onModuleLoaded`: **renomeado**. No host do wrapper: `moduleLoaded`. * `onTimeoutButtonClick`: **renomeado** para `timeoutErrorButtonClick`. * `onStabilizing`: **renomeado** para `stabilizing`. **Métodos** * `checkCapabilities()`: **deprecado**. Esta funcionalidade foi substituída pelo subpath `@facephi/sdk-web-wc/capabilities.mjs` da biblioteca SDK Web, invocável antes de montar o SDK Provider. Os widgets também a expõem em seu próprio subpath `/capabilities.mjs`. * `mountExternalCamera()`: **deprecado**. Esta funcionalidade foi substituída pelo uso da propriedade `externalCamera` nos wrappers Selphi e SelphID do SDK Web. * `generateTemplateRawFromByteArray()`: **deprecado**. Esta funcionalidade é implementada internamente nas versões mais recentes dos componentes. #### SelphID Widget Mudanças incompatíveis associadas ao SelphID em relação às versões mais recentes do SDK Web. **Propriedades** * `licenseKey`: **deprecado**. Agora a licença é gerenciada internamente por meio da apikey do SDK Provider. * `bundlePath`: **deprecado**. Agora o download e a referência dos recursos são feitos internamente de forma automática. * `tokenizer`: **renomeado**. A prop do wrapper é `tokenize` (boolean para o motor). * `specificdata`: **renomeado** para `enabledCountries` (anteriormente `countryFilter`). * `documentMode`: **renomeado** para `expectedSides` (tipado como `ExpectedSides`). * `cameraSelection`: **renomeado** para `cameraSwitch`. * `retryOnlyCurrentSide`: **renomeado** para `retryCurrentSide`. * `videoQuality`: **renomeado** para `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **atualizado** para `showTutorial` (lógica inversa em relação a “mostrar tutorial”; substitui `disableTutorial`). * `previewCapture`: **renomeado** para `showResultAfterCapture` (anteriormente `previewImage`). * `allowUnknownDocuments`: **renomeado** para `allowUnknown`. * `debugMode`: **renomeado** para `Debug`. * `documentType`: **atualizado**. O wrapper aceita `DocumentType`, arrays e strings. * `language`: **deprecado**. Os idiomas são gerenciados com a propriedade `language` do SDK Provider. * `askSimpleMode`: **deprecado**. Esta funcionalidade pode ser substituída pelo uso do componente [File Uploader](/docs.facephi-pt-br/sdks/sdk-web/componentes/file-uploader-cargador-de-archivos.md). * `preloadingMessage`: **deprecado**. * `dpiList`: **atualizado** para `dpi`. * `resourcesPath`: **deprecado**. * `acessibilidade`: **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`: **renomeado**. No host do wrapper: `moduleLoaded`. * `onExtractionFinished`: **renomeado** para `extractionFinish`. * `onUserCancelled`: **renomeado** para `userCancel`. * `onTimeoutButtonClick`: **renomeado** para `timeoutErrorButtonClick`. **Métodos** * `checkCapabilities()`: **deprecado**. Esta funcionalidade foi substituída pelo subpath `@facephi/sdk-web-wc/capabilities.mjs` da biblioteca SDK Web, invocável antes de montar o SDK Provider. Os widgets também a expõem em seu próprio subpath `/capabilities.mjs`. * `mountExternalCamera()`: **deprecado**. Esta funcionalidade foi substituída pelo uso da propriedade `externalCamera` nos wrappers Selphi e SelphID do SDK Web. * `generateBrowserCache()`: **deprecado**. Agora é a biblioteca SDK Web que oferece os métodos `generateSelphiBrowserCache()` e `generateSelphIDBrowserCache()`. *** ### **Guia passo a passo para a migração** 1. **Desinstalar** widgets legados e **eliminar** possíveis arquivos tgz e arquivos ZIP, scripts soltos e pastas de recursos usadas apenas por esses widgets. 1. Desinstalar bibliotecas legadas: 
// package.json
      ...
      "dependencies": {
          "@facephi/selphid-widget-web": "file:facephi-selphid-widget-web-*.tgz", <- Eliminar
          "@facephi/selphi-widget-web": "file:facephi-selphi-widget-web-*.tgz", <- Remover
          ...
      }
2. Remover arquivos legados (arquivos TGZ, ZIP, scripts...): 
facephi-selphid-widget-web-*.tgz  <- Remover
      facephi-selphi-widget-web-*.tgz  <- Remover
3. Remover pastas de recursos com seu conteúdo: 
assets/
          selphi/  <- Remover
          selphid/  <- Remover
2. **Instalar** `@facephi/sdk-web-wc` **3.x** e integrar **``** como indicado na [guia de instalação](/docs.facephi-pt-br/sdks/sdk-web/introduccion/instalacion.md). 1. Adicionar dependência do SDK Web 3: 
// package.json
      ...
      "dependencies": {
          "@facephi/sdk-web-wc": "latest",
          ...
      }
2. Preparar arquivo de credenciais `.npmrc` com os dados necessários: ``` @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 a biblioteca: ```bash npm install ``` 3. **Instanciação** de **``, substituir tags legadas** por **``** e **``** (nomes, propriedades e eventos diferentes dos do 5.x / 4.x) e restauração do fluxo de negócio como indicado na seção [Primeiros Passos](/docs.facephi-pt-br/sdks/sdk-web/introduccion/primeros-pasos.md). 1. Definir os elementos customizados da biblioteca no arquivo principal do projeto: 
// main.js
      import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader';
      defineFacephiSdkCustomComponent(window);
2. Instanciação de SDK Provider e sua configuração: ```jsx ``` > **Aviso**: Os componentes devem estar **dentro** da tag **`facephi-sdk-provider`** e usar a marcação correta dos componentes: > > * **SelphID**: Agora usa a tag `facelphi-selphid-widget`. > * **Selphi**: Agora usa a tag `facelphi-selphi-widget`. 3. Restaurar/implementar fluxo entre componentes: 
function onSelphIDExtractionFinish(event) {
          const result = event.detail;
          console.log("[SELPHID] ExtractionFinish", result);
          // Cargar Selphi uma vez que SelphID tenha finalizado a extração
          initializeSelphiWidget();
      }
> Este exemplo usa JavaScript para a navegação entre componentes como exemplo. > > **Facephi recomenda** o uso de sistemas mais avançados e escaláveis, como typescript, frameworks, routers... Cada implementação pode diferenciar o método ou elemento a carregar. 4. **Resolver quebras de compatibilidade**: Atualizar as propriedades e eventos que exijam mudanças de referência ou valor, bem como eliminar os elementos obsoletos.\ Para isso deixamos um guia de [referência com os elementos atualizados, renomeados ou obsoletos](#breaking-changes-entre-legacy-y-sdk-web-3) nesta documentação. 1. Atualizar a funcionalidade dos novos componentes para recuperar o funcionamento desejado. 2. Caso haja um design personalizado prévio, é necessário integrá-lo ao novo sistema de design. Para esse processo, é possível consultar [a guia de Personalização do SDK Web](/docs.facephi-pt-br/sdks/sdk-web/personalizacion.md). 3. Por fim, restaria apenas realizar uma bateria de testes nos dispositivos que se considerar para garantir que o funcionamento está correto e atende aos critérios necessários.
**Fluxo de negócio:** a ordem dos passos (por exemplo Selphi → SelphID → backend), a **orquestração em JavaScript**, os **routers** de SPA e o estado da aplicação **podem ser mantidos**; só deve ser reimplementada a **captura Facephi** dentro do SDK Web 3 com as possíveis mudanças dos novos componentes.