Configuração adicional

Guias de configuração para implementações em ambientes especiais.

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

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

---

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

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.

Política recomendada:

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

Se aparecer "Refused to create a worker from 'blob:…'", adicione blob: para worker-src (ou child-src em navegadores antigos).

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:

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

Endpoint	Protocolo	URL
/licensing	https	https://license.identity-platform.io
/tracking	https	https://idv-ing-proxy.eu.idv-suite.com
/qr	wss	https://sdk-web-services.facephi.pro
/identification	wss	https://video-identification.eu.idv-suite.com
/resources	https	https://widget-components.facephi.pro/
/auth	https	https://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.

A Facephi se encarregará de fornecer as URLs necessárias em cada caso.

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.

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.

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.

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.

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.

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.

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:

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

• Revise as seções específicas de cada módulo, como Selphi, SelphID ou Video Recording.