> 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/introduccion/configuracion-adicional.md). # Configuração adicional ## Pré-carga de recursos de Selphi e SelphID O pacote `@facephi/sdk-web-wc` exporta as utilidades `generateSelphiBrowserCache` e `generateSelphIDBrowserCache` para baixar no navegador os recursos dos motores de Selphi e SelphID **antes** de que `` se monte no DOM. Se forem invocadas com antecedência, podem reduzir o tempo de carregamento percebido quando o usuário inicia o Fluxo biométrico, já que os assets do Widget já estarão disponíveis no cache do navegador. Devem ser chamadas **antes** de integrar o SDK Provider na página. Se o provedor já estiver no DOM, este passo não traz benefício. ```javascript import { generateSelphiBrowserCache, generateSelphIDBrowserCache, } from '@facephi/sdk-web-wc'; // Baixar recursos antes de montar o SDK Provider await generateSelphiBrowserCache(process.env.FACEPHI_SDK_APIKEY); await generateSelphIDBrowserCache(process.env.FACEPHI_SDK_APIKEY); ``` Parâmetros: * `apiKey` (`string`): ApiKey com Licença para o Widget correspondente. * `engineLocation` (`string`, opcional): Caminho personalizado dos recursos do motor. Para mais detalhes, consulte a documentação de cada utilidade em [generateSelphiBrowserCache](/docs.facephi-pt-br/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphibrowsercache.md) e [generateSelphIDBrowserCache](/docs.facephi-pt-br/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphidbrowsercache.md). *** ## Política de Segurança de Conteúdo (CSP) Se sua aplicação usa cabeçalhos CSP rígidos, você deve permitir explicitamente as origens de que o SDK Web e os Widgets biométricos precisam (scripts, workers, mídia e APIs). {% hint style="info" %} Aplique estas diretivas no **servidor da sua aplicação**. Os servidores da Facephi já operam com CORS; não é necessário replicar esses cabeçalhos neles. {% endhint %} **Política recomendada:** ```http Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://widget-components.facephi.pro; media-src 'self' blob:; worker-src 'self' blob:; connect-src 'self' https://widget-components.facephi.pro https://sdk-web.facephi.pro https://sdk-web-services.facephi.pro https://api.identity-platform.io https://license.identity-platform.io; ``` | Diretiva | O que habilita | | -------------------- | --------------------------------------------------------------------------------------------- | | `default-src 'self'` | Somente recursos da mesma origem por padrão | | `script-src` | Scripts próprios, Inicialização do SDK, `blob:` e recursos de `widget-components.facephi.pro` | | `media-src` | Captura e reprodução de câmera/microfone (`blob:`) | | `worker-src` | Web Workers gerados em memória pelo SDK (`blob:`) | | `connect-src` | APIs biométricas, Licenças e Identity Platform | {% hint style="warning" %} Se aparecer *"Refused to create a worker from 'blob:…'"*, adicione `blob:` para `worker-src` (ou `child-src` em navegadores antigos). {% endhint %} **Cabeçalhos complementares** (configurar no mesmo servidor ou proxy): | Cabeçalho | Valor | | ------------------------------ | ------------------------------ | | `Permissions-Policy` | `camera=self, microphone=self` | | `Referrer-Policy` | `A barra final (` | | `X-Content-Type-Options` | `nosniff` | | `Cross-Origin-Embedder-Policy` | `require-corp` | | `Cross-Origin-Opener-Policy` | `same-origin` | | `Cross-Origin-Resource-Policy` | `same-origin` | Valide a configuração em staging antes da produção. Se você só precisa habilitar a CDN do SDK: ```plaintext script-src 'self' https://sdk-web.facephi.pro; connect-src 'self' https://sdk-web.facephi.pro; ``` *** ## Integração em aplicações nativas por meio de WebView * Você pode usar o SDK dentro de uma aplicação nativa por meio de um WebView usando a integração do site do seu provedor de SDK da Facephi. Recomendamos personalizar o User-Agent do seu WebView adicionando um token personalizado em vez de substituir completamente o UA. #### Exemplos de User-Agent * ❌ Exemplo incorreto: Código ``` sdkwebview ``` * ✅ Exemplo correto (Android): Código ``` Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/115.0.0.0 Mobile Safari/537.36 sdkwebview ``` * ✅ Exemplo correto (iOS): Código ``` Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 como Mac OS X) AppleWebKit/605.1.15 (KHTML, como Gecko) Mobile/15E148 sdkwebview ``` #### Notas * O User-Agent base pode refletir o dispositivo/SO mínimo compatível; o último token deve ser `sdkwebview`. * Para aplicações iOS desenvolvidas com Swift e Storyboards, habilite a reprodução em linha no WKWebView (Inline Playback / `allowsInlineMediaPlayback = true`). *** ## Guia de Configuração de Proxy Este guia fornece exemplos prontos para uso de um proxy de encaminhamento (forward proxy). O exemplo será feito com Nginx, mas pode ser feito com a tecnologia de sua escolha. ### Tabela de Rotas
EndpointProtocoloURL
/licensinghttpshttps://license.identity-platform.io
/trackinghttpshttps://idv-ing-proxy.eu.idv-suite.com
/qrwsshttps://sdk-web-services.facephi.pro
/identificationwsshttps://video-identification.eu.idv-suite.com
/resourceshttpshttps://widget-components.facephi.pro/
/authhttpshttps://idv-ing-proxy.eu.idv-suite.com
O proxy deve remover a rota base e encaminhar a requisição ao Endpoint de destino, preservando o caminho URL restante. {% hint style="info" %} A Facephi se encarregará de fornecer as URLs necessárias em cada caso. {% endhint %} ### Serviço de Licenças Este serviço de licenças requer que o motor HTTP atue como um proxy de encaminhamento para um backend HTTPS externo, estabelecendo o SNI correto para o servidor de destino e reenviando os cabeçalhos de solicitação originais enquanto substitui o cabeçalho Host pelo nome de host do servidor de destino. Será responsabilidade do integrador emitir as políticas CORS. ```nginx location /licensing { proxy_pass https://license.identity-platform.io/; proxy_ssl_server_name on; proxy_pass_request_headers on; proxy_set_header Host license.identity-platform.io; # Ocultar os cabeçalhos CORS do backend para evitar duplicados proxy_hide_header Access-Control-Allow-Origin; proxy_hide_header Access-Control-Allow-Methods; proxy_hide_header Access-Control-Allow-Headers; proxy_hide_header Access-Control-Allow-Credentials; # CORS controlado apenas pelo Nginx add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; # Tratamento do preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` *** ### Serviço de Rastreamento (Tracking) Este serviço de rastreamento requer que o motor HTTP atue como um proxy de encaminhamento para um backend HTTPS externo, estabelecendo o SNI correto para o servidor de destino e encaminhando os cabeçalhos de solicitação originais enquanto substitui o cabeçalho Host pelo nome de host do servidor de destino. Será responsabilidade do integrador emitir as políticas CORS. ```nginx location /tracking/ { proxy_pass https://api.identity-platform.io/; proxy_ssl_server_name on; proxy_pass_request_headers on; proxy_set_header Host api.identity-platform.io; # Ocultar os cabeçalhos CORS do backend (evitar duplicados) proxy_hide_header Access-Control-Allow-Origin; proxy_hide_header Access-Control-Allow-Methods; proxy_hide_header Access-Control-Allow-Headers; proxy_hide_header Access-Control-Allow-Credentials; # CORS: Ajuste a origem conforme o seu frontend add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; # Preflight (OPTIONS) if ($request_method = OPTIONS) { return 204; } } ``` *** ### Serviço QR Este serviço QR requer que o motor HTTP atue como um proxy de encaminhamento para um backend WebSocket externo, estabelecendo o SNI correto para o servidor de destino e encaminhando os cabeçalhos de proxy essenciais enquanto substitui o cabeçalho Host pelo nome de host do servidor de destino. O motor deve ser configurado para suportar as atualizações de protocolo HTTP/1.1, preservando os cabeçalhos Upgrade e Connection para habilitar a conectividade WebSocket. A política CORS deve ser definida pelo integrador de acordo com seus requisitos de segurança, e o proxy deve expor cabeçalhos de resposta específicos como Content-Length e Content-Range para permitir que essas informações sejam acessadas no lado do cliente. ```nginx location /qr { proxy_pass https://sdk-web-services.facephi.pro/; # Configuração específica de WebSocket proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Cabeçalhos padrão proxy_set_header Host ws.example.com; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # CORS para WebSockets (opcional) add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; } ``` Requisitos de WebSocket: * `proxy_http_version 1.1` é obrigatório * Os cabeçalhos `Upgrade` e `Connection` são necessários para o *handshake* *** ### Serviço de Gravação de Vídeo Este serviço de gravação de vídeo requer que o motor HTTP atue como proxy reverso para um backend WebSocket externo para identificação por vídeo em tempo real. O motor deve ser configurado para suportar atualizações de protocolo HTTP/1.1, preservando os cabeçalhos Upgrade e Connection para habilitar a conectividade WebSocket. Timeouts estendidos são configurados para manter conexões persistentes durante as sessões de vídeo. A política CORS deve ser definida pelo integrador de acordo com seus requisitos de segurança. ```nginx location /identification { proxy_pass https://video-identification.eu.idv-suite.com; proxy_ssl_server_name on; # Configuração específica para WebSocket proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Cabeçalhos padrão proxy_set_header Host FACEPHI_INTERNAL_URL; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Timeout de WebSocket (manter a conexão ativa) proxy_read_timeout 86400s; proxy_send_timeout 86400s; # CORS para WebSockets add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; # Tratamento de preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` **Requisitos de WebSocket:** * `proxy_http_version 1.1` é obrigatório * Os cabeçalhos `Upgrade` e `Connection` são necessários para o handshake *** ### Serviço de recursos Este serviço de recursos requer que o motor HTTP atue como proxy reverso para um backend HTTPS externo, estabelecendo o SNI correto para o servidor de destino e encaminhando os cabeçalhos originais da solicitação, substituindo o cabeçalho Host pelo nome de host do servidor de destino. Será responsabilidade do integrador definir as políticas CORS. ```nginx location /resources/ { proxy_pass https://widget-components.facephi.pro/; proxy_ssl_server_name on; proxy_pass_request_headers on; proxy_set_header Host widget-components.facephi.pro/; # Ocultar cabeçalhos CORS do backend (evitar duplicados) proxy_hide_header Access-Control-Allow-Origin; proxy_hide_header Access-Control-Allow-Methods; proxy_hide_header Access-Control-Allow-Headers; proxy_hide_header Access-Control-Allow-Credentials; # CORS: ajuste a origem conforme o seu frontend add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; # Preflight (OPTIONS) if ($request_method = OPTIONS) { return 204; } } ``` *** ### Serviço de autenticação da API Este serviço de autenticação requer que o motor HTTP atue como proxy reverso para um backend HTTPS externo, estabelecendo o SNI correto para o servidor de destino e encaminhando os cabeçalhos originais da solicitação, substituindo o cabeçalho Host pelo nome de host do servidor de destino. Será responsabilidade do integrador definir as políticas CORS. ```nginx location /auth/ { proxy_pass https://idv-ing-proxy.eu.idv-suite.com; proxy_ssl_server_name on; proxy_pass_request_headers on; proxy_set_header Host idv-ing-proxy.eu.idv-suite.com; # Ocultar cabeçalhos CORS do backend para evitar duplicados proxy_hide_header Access-Control-Allow-Origin; proxy_hide_header Access-Control-Allow-Methods; proxy_hide_header Access-Control-Allow-Headers; proxy_hide_header Access-Control-Allow-Credentials; # CORS controlado apenas pelo Nginx add_header 'Access-Control-Allow-Origin' '*' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' '*' always; add_header 'Access-Control-Allow-Credentials' 'true' always; # Tratamento de preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` *** ## Notas de Configuração **🔀 Comportamento de `proxy_pass`** A barra final (`barra final`) é importante: ```nginx # COM barra final: reescreve a rota location /api { proxy_pass https://backend.com/; # /api/users -> https://backend.com/users } # SEM barra final: preserva o caminho completo location /api { proxy_pass https://backend.com; # /api/users -> https://backend.com/api/users } ``` **🌐 CORS** * Ajuste `Access-Control-Allow-Origin` ao seu domínio específico. * Você pode usar `*` em desenvolvimento, mas NUNCA em produção com credenciais. * `proxy_hide_header` evita conflitos quando o backend já envia cabeçalhos CORS. **📝 Cabeçalhos comuns** * `proxy_set_header Host $host;` # Domínio solicitado * `proxy_set_header X-Real-IP $remote_addr;` # IP do cliente * `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;` # Cadeia de IP * `proxy_set_header X-Forwarded-Proto $scheme;` # http ou https *** ## Comandos úteis Validar a configuração `nginx -t` Recarregar a configuração (sem tempo de inatividade) `nginx -s reload` Ver os logs de erro `tail -f /var/log/nginx/error.log` Ver os logs de acesso `tail -f /var/log/nginx/access.log` Reiniciar Nginx `systemctl restart nginx` `# ou` `service nginx restart` *** ## Próximos passos * Configure os Componentes e módulos conforme suas necessidades. * Explore os [Exemplos de integração](/docs.facephi-pt-br/produtos/landing/ejemplos-de-integracion.md). * Revise as seções específicas de cada módulo, como [Selphi](/docs.facephi-pt-br/sdks/sdk-web/componentes/selphi-biometria-facial.md), [SelphID](/docs.facephi-pt-br/sdks/sdk-web/componentes/selphid-documentos.md) ou [Video Recording](/docs.facephi-pt-br/sdks/sdk-web/componentes/video-recording-video-grabacion.md).