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

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

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

Tema
Antes
No SDK Web 3

Recursos

bundlePath e pastas de recursos obrigatórias (SDK 2 ou widgets .tgz)

Carregamento padrão a partir de CDN; bundlePath Desnecessário

Implementação

Manual, exigia atualizar recursos, instável

Implementação unificada, resumida e estável.

Licença

Licenciamento individual por produto

Uso centralizado com apiKey o SDK Provider (facilitada por Facephi)

Personalização visual

Limitada e distribuída conforme widget/pacote

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

Só disponível em SelphID 4.x

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

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.

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 (<facephi-selphid> | <facephi-selphi>): renomeadas. Em seu lugar será usado <facephi-selphid-widget> e <facephi-selphi-widget> e permanecerão dentro da etiqueta <facephi-sdk-provider>.

  • 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 e a seção Nomes de propriedade recomendados.

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

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

    2. Excluir arquivos legacy (arquivos TGZ, ZIP, scripts...):

    3. Excluir pastas de recursos com seu conteúdo:

  2. Instalar @facephi/sdk-web-wc 3.x e integrar <facephi-sdk-provider> conforme indicado na guia de instalação.

    1. Adicionar dependência do SDK Web 3:

    2. Preparar arquivo de credenciais .npmrc com os dados necessários:

    3. Instalar a biblioteca:

  3. Instanciação de <facephi-sdk-provider>, substituir etiquetas legacy por <facephi-selphi-widget> e <facephi-selphid-widget> (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.

    1. Definir custom elements da biblioteca no arquivo principal do projeto:

    2. Instanciação de SDK Provider e sua configuração:

      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:

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

    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.

AnteriorPerguntas e erros frequentesPróximoChangelog

Atualizado