> 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 ## SDK Web 3 - Melhorias e principais mudanças As versões anteriores de **SDK Web 2.x, Widgets Selphi 5.x e SelphID 4.x são consideradas descontinuadas** 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 geralmente mais rápido e estável. * **Novas funcionalidades**: As últimas versões do SDK Web contam com todas as novas funcionalidades desenvolvidas até o momento. * **Desempenho:** Os componentes da biblioteca utilizam 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 atual de produto 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 caminhos 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 o SDK Provider (facilitada por Facephi)
Personalização visualLimitada e distribuída conforme widget/pacoteSistema de variáveis CSS em facephi-sdk-provider; textos personalizáveis via json; recursos personalizáveis (logo, loadingAnimation, tutorialAnimations)
Métodos de pré-carregamento no navegadorSó disponível em SelphID 4.xMétodos generateSelphiBrowserCache e generateSelphIDBrowserCache no SDK Provider
*** ### Vantagens do uso do CDN * Integração mais simples. * Menor manutenção de infraestrutura para os recursos do SDK. * Atualizações automáticas dos recursos servidos pelo CDN. #### Aspectos a levar em conta com a CDN **Política de segurança de conteúdo (CSP)** Se a aplicação usar 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 produzir 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 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 das 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 excluir pastas de recursos** que serviam apenas ao 2.x. As versões mais recentes 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 é totalmente 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 em relação à 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 do Selphi e do SelphID em suas versões 6.x, aproveitando todas as melhorias que oferecem. **integrações legacy:** 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 legacy** 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 com a 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 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 relação às últimas versões do SDK Web. * API imperativa e utilidades (`FPhi.SelphID.*` e `FPhi.Selphi.*`): **descontinuado** como referência de integração. O zip legacy não deve mais ser tomado como fonte da 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 funcional, mas fica descontinuado 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`: `Frontal`/`Traseira`). Só Selphi: * `livenessMoveSteps`: **preferido** `moveSuccessfulAttempts`. * `livenessMoveFailedAttempts`: **preferido** `moveFailedAttempts`. * Novo `livenessMode` (enum `LivenessMode`) para selecionar o modo de teste de vida. Só SelphID: * `chooseDocument`: **preferido** `showDocumentSelector`. * `countryFilter`: **preferido** `enabledCountries`. #### Selphi Widget Mudanças incompatíveis associadas ao Selphi em relação às últimas versões do SDK Web. **Propriedades** * `bundlePath`: **descontinuado**. Agora o download e a referência dos recursos são feitos internamente de forma automática. * `videoQuality`: **renomeado** a `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **atualizado** a `showTutorial` (lógica inversa em relação a “mostrar tutorial”; substitui `disableTutorial`). * `previewCapture`: **renomeado** a `showResultAfterCapture` (anteriormente `previewImage`). * `debugMode`: **renomeado** a `debug`. * `language`: **descontinuado**. Os idiomas são gerenciados com a propriedade `language` do SDK Provider. * `antispoofEnabled`: **renomeado** a `antispoof`. * `stabilizationStage`: **renomeado** a `stabilization`. * `cameraSwitchButton`: **renomeado** a `cameraSwitch`. * `dpiList`: **descontinuado**. * `resourcesPath`: **descontinuado**. * `bundlePathExternal`: **descontinuado**. * `preloadingMessage`: **descontinuado**. * `accessibility`: **descontinuado**. * `accessibleElements`: **descontinuado**. * `graphPath`: **descontinuado**. * `ephemeralKey`: **descontinuado**. * `videoRecordScale`: **descontinuado**. * `livenessMode`: **disponível a partir de 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`: **descontinuado**. * `livenessMoveInitialError`: **descontinuado**. * `livenessMoveInfoTime`: **descontinuado**. * `authenticateTime`: **descontinuado**. * `minLogImages`: **descontinuado**. * `cropImage`: **descontinuado**. **Eventos** * `onModuleLoaded`: **renomeado**. No host do wrapper: `moduleLoaded`. * `onTimeoutButtonClick`: **renomeado** a `timeoutErrorButtonClick`. * `onStabilizing`: **renomeado** a `stabilizing`. **Métodos** * `checkCapabilities()`: **descontinuado**. Essa funcionalidade vem implementada internamente nas últimas versões dos componentes. * `mountExternalCamera()`: **descontinuado**. Essa funcionalidade foi substituída pelo uso da propriedade `externalCamera` nos wrappers Selphi e SelphID do SDK Web. * `generateTemplateRawFromByteArray()`: **descontinuado**. Essa funcionalidade vem implementada internamente nas últimas versões dos componentes. #### SelphID Widget Mudanças incompatíveis associadas ao SelphID em relação às últimas versões do SDK Web. **Propriedades** * `licenseKey`: **descontinuado**. Agora a licença é gerenciada internamente por meio da apikey do SDK Provider. * `bundlePath`: **descontinuado**. 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** a `enabledCountries` (anteriormente `countryFilter`). * `documentMode`: **renomeado** a `expectedSides` (tipado como `ExpectedSides`). * `cameraSelection`: **renomeado** a `cameraSwitch`. * `retryOnlyCurrentSide`: **renomeado** a `retryCurrentSide`. * `videoQuality`: **renomeado** a `videoRecordQuality` (tipado como `VideoRecordQuality`). * `tutorial`: **atualizado** a `showTutorial` (lógica inversa em relação a “mostrar tutorial”; substitui `disableTutorial`). * `previewCapture`: **renomeado** a `showResultAfterCapture` (anteriormente `previewImage`). * `allowUnknownDocuments`: **renomeado** a `allowUnknown`. * `debugMode`: **renomeado** a `debug`. * `documentType`: **atualizado**. O wrapper aceita `DocumentType`, arrays e strings. * `language`: **descontinuado**. Os idiomas são gerenciados com a propriedade `language` do SDK Provider. * `askSimpleMode`: **descontinuado**. Essa 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`: **descontinuado**. * `dpiList`: **atualizado** a `dpi`. * `resourcesPath`: **descontinuado**. * `accessibility`: **descontinuado**. * `accessibleElements`: **descontinuado**. * `graphPath`: **descontinuado**. * `ephemeralKey`: **descontinuado**. * `videoRecordScale`: **descontinuado**. * `mode`: **descontinuado**. * `forceLandscape`: **descontinuado**. * `canvasHD`: **descontinuado**. * `startSimpleMode`: **descontinuado**. * `cameraMirror`: **descontinuado**. * `scanMode`: **descontinuado**. * `documentAspectRatio`: **descontinuado**. **Eventos** * `onModuleLoaded`: **renomeado**. No host do wrapper: `moduleLoaded`. * `onExtractionFinished`: **renomeado** a `extractionFinish`. * `onUserCancelled`: **renomeado** a `userCancel`. * `onTimeoutButtonClick`: **renomeado** a `timeoutErrorButtonClick`. **Métodos** * `checkCapabilities()`: **descontinuado**. Essa funcionalidade vem implementada internamente nas últimas versões dos componentes. * `mountExternalCamera()`: **descontinuado**. Essa funcionalidade foi substituída pelo uso da propriedade `externalCamera` nos wrappers Selphi e SelphID do SDK Web. * `generateBrowserCache()`: **descontinuado**. Agora é a biblioteca SDK Web que oferece os métodos `generateSelphiBrowserCache()` e `generateSelphIDBrowserCache()`. *** ### **Guia passo a passo para a migração** 1. **Desinstalar** widgets legacy e **excluir** possíveis arquivos tgz e arquivos ZIP, scripts soltos e pastas de recursos usadas apenas por esses widgets. 1. Desinstalar bibliotecas legacy: 
// package.json
      ...
      "dependencies": {
          "@facephi/selphid-widget-web": "file:facephi-selphid-widget-web-*.tgz", <- Excluir
          "@facephi/selphi-widget-web": "file:facephi-selphi-widget-web-*.tgz", <- Excluir
          ...
      }
2. Excluir arquivos legacy (arquivos TGZ, ZIP, scripts...): 
facephi-selphid-widget-web-*.tgz  <- Excluir
      facephi-selphi-widget-web-*.tgz  <- Excluir
3. Excluir pastas de recursos com seu conteúdo: 
assets/
          selphi/  <- Excluir
          selphid/  <- Excluir
2. **Instalar** `@facephi/sdk-web-wc` **3.x** e integrar **``** conforme 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 etiquetas legacy** por **``** e **``** (nomes, propriedades e eventos diferentes dos do 5.x / 4.x) e restauração do fluxo de negócio conforme indicado na seção [Primeiros Passos](/docs.facephi-pt-br/sdks/sdk-web/introduccion/primeros-pasos.md). 1. Definir custom elements 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 utilizar a marcação correta dos componentes: > > * **SelphID**: Agora utiliza a tag `facelphi-selphid-widget`. > * **Selphi**: Agora utiliza a tag `facelphi-selphi-widget`. 3. Restaurar/implementar fluxo entre componentes: 
function onSelphIDExtractionFinish(event) {
          const result = event.detail;
          console.log("[SELPHID] ExtractionFinish", result);
          // Carregar Selphi uma vez que SelphID tenha finalizado a extração
          initializeSelphiWidget();
      }
> Este exemplo utiliza 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 ser carregado. 4. **Resolver mudanças incompatíveis**: Atualizar as propriedades e eventos que requeiram mudanças de referência ou valor, bem como remover os elementos descontinuados.\ Para isso, deixamos um guia de [referência com os elementos atualizados, renomeados ou descontinuados](#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 exista um design personalizado prévio, é necessário integrá-lo ao novo sistema de design. Para esse processo, é possível consultar [o guia de Personalização do SDK Web](/docs.facephi-pt-br/sdks/sdk-web/personalizacion.md). 3. Por fim, só restaria realizar uma bateria de testes nos dispositivos que se considerar, para garantir que o funcionamento seja o correto e cumpra os critérios necessários.
**Fluxo de negócio:** a ordem das etapas (por exemplo Selphi → SelphID → backend), a **orquestração em JavaScript**, os **roteadores** 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.