Perguntas e erros frequentes

Esta seção descreve alguns dos problemas mais comuns que podem surgir ao integrar o SDK Web.

Compatibilidade com Turbopack

Alguns frameworks modernos, como Next.js 16, usam Turbopack como bundler padrão. Turbopack atualmente tem algumas limitações que causam problemas de compatibilidade com a distribuição padrão do SDK Web.

Uso da Versão Bundle

Para usar o SDK Web com frameworks habilitados para Turbopack, você deve importar do ponto de entrada bundle:

import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';

Para poder usar este módulo quando se usa TypeScript, ele deve ser declarado em um arquivo .d.ts da seguinte forma:

// global.d.ts
declare module '@facephi/sdk-web-wc/bundle';

No entanto, tem algumas limitações descritas a seguir.

Considerações sobre Importações de Tipos

Você pode importar tipos puros de TypeScript a partir do pacote principal usando import type:

import type { ErrorData, SelphiWidgetLoadedEvent, SelphiExtractionFinishEvent } from '@facephi/sdk-web-wc';

No entanto, enums como Language e TypeFamily não podem ser importados de @facephi/sdk-web-wc.

Solução: Use valores literais de string diretamente:

<facephi-sdk-provider
  type={'ONBOARDING'}           // em vez de TypeFamily.onboarding
  language={'en'}               // em vez de Language.en
>

Aviso: Nem todas as propriedades aceitam esse tipo de configuração. Isso só é válido para as propriedades com valores simples (string, number, boolean...).

Exemplo (Implementação em Next.js 16)

'use client';
import type { 
  ErrorData, 
  SelphiWidgetLoadedEvent, 
  SelphiExtractionFinishEvent, 
  FacephiSelphiWidgetCustomEvent 
} from '@facephi/sdk-web-wc';
import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';

// Eventos do Provider
function handleEmitData(event: CustomEvent<{ operationId: string; sessionId: string; extraData: string }>) {
  const result = event.detail;
}

// Eventos de Selphi
function handleModuleLoaded(event: FacephiSelphiWidgetCustomEvent<SelphiWidgetLoadedEvent>) {
  const result = event.detail.detail;
}

function handleExtractionFinish(event: FacephiSelphiWidgetCustomEvent<SelphiExtractionFinishEvent>) {
  const result = event.detail.detail;
}

return (
  <facephi-sdk-provider
    apikey={apiKey}
    type={TypeFamily.onboarding}
    language={Language.en}
    onemitData={handleEmitData}
  >
    <facephi-selphi-widget
      interactible={true}
      previewImage={true}
      onModuleLoaded={handleModuleLoaded}
      onExtractionFinish={handleExtractionFinish}
    />
  </facephi-sdk-provider>
);

Compatibilidade com Wrappers de React e Angular

Os pacotes @facephi/sdk-web-react e @facephi/sdk-web-angular atualmente não são compatíveis com Turbopack porque internamente importam de @facephi/sdk-web-wc (não a versão bundle), o que provoca os mesmos problemas de compatibilidade. Para ambientes com Turbopack, use Web Components nativos com a versão bundle e tratamento manual de eventos como mostrado acima.

---

Integração Incorreta de APIKEY

Uma integração incorreta do apikey pode levar a vários problemas. A seguir, são descritos os mais comuns:

1. Erro de Configuração Web

É um requisito obrigatório fornecer à Facephi um domínio web válido onde o SDK será utilizado. Se o SDK for implantado em um domínio web diferente, você encontrará um erro conhecido do navegador chamado CORS (Cross-Origin Resource Sharing).

O que é CORS?

CORS é uma restrição de segurança aplicada pelos navegadores web que limita as interações entre um servidor web e APIs externas. Neste caso, quando o site do cliente se comunica com o serviço de licenças da Facephi, falhará se o domínio web do cliente não estiver corretamente configurado durante a configuração da APIKEY.

Como Evitar Erros CORS?

• Certifique-se de que o domínio web correto seja compartilhado com a equipe de Suporte da Facephi ao solicitar a APIKEY.

• Implante o SDK exclusivamente no domínio autorizado.

---

2. Erro de Configuração de Componentes

O apikey está vinculado aos componentes que o cliente contratou, que estão pré-configurados pela equipe de Suporte da Facephi. Se um componente específico, como Selphid ou Selphi, não estiver habilitado, esses componentes não serão renderizados na web, mesmo que tenham sido integrados no nível de código.

Depuração de Erros de Configuração de Componentes

Para depurar esses erros, você pode habilitar o parâmetro debug no facephi-sdk-provider. Isso fornecerá logs detalhados e ajudará a identificar configurações incorretas.

Exemplo: Habilitar Debug

import { TrackingSteps, TypeFamily } from '@facephi/sdk-web-wc';

<facephi-sdk-provider
  apikey={process.env.FACEPHI_SDK_APIKEY}
  debug={true}
  steps={`${TrackingSteps.start},${TrackingSteps.selphiWidget},${TrackingSteps.selphidWidget},${TrackingSteps.finish}`}
  customerId={customerId}
  type={TypeFamily.onboarding}
/>