> 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/sdks/sdk-web/introduccion/configuracion-adicional.md). # Configuración adicional ## Precarga de recursos de Selphi y SelphID El paquete `@facephi/sdk-web-wc` exporta las utilidades `generateSelphiBrowserCache` y `generateSelphIDBrowserCache` para descargar en el navegador los recursos de los motores de Selphi y SelphID **antes** de que `` se monte en el DOM. Si se invocan con antelación, pueden reducir el tiempo de carga percibido cuando el usuario inicia el flujo biométrico, ya que los assets del widget ya estarán disponibles en caché del navegador. Deben llamarse **antes** de integrar el SDK Provider en la página. Si el proveedor ya está en el DOM, este paso no aporta beneficio. ```javascript import { generateSelphiBrowserCache, generateSelphIDBrowserCache, } from '@facephi/sdk-web-wc'; // Descargar recursos antes de montar el SDK Provider await generateSelphiBrowserCache(process.env.FACEPHI_SDK_APIKEY); await generateSelphIDBrowserCache(process.env.FACEPHI_SDK_APIKEY); ``` Parámetros: * `apiKey` (`string`): ApiKey con licencia para el widget correspondiente. * `engineLocation` (`string`, opcional): Ruta personalizada de los recursos del motor. Para más detalle consulta la documentación de cada utilidad en [generateSelphiBrowserCache](/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphibrowsercache.md) y [generateSelphIDBrowserCache](/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphidbrowsercache.md). *** ## Content Security Policy (CSP) Si tu aplicación usa cabeceras CSP estrictas, debes permitir explícitamente los orígenes que el SDK Web y los widgets biométricos necesitan (scripts, workers, medios y APIs). {% hint style="info" %} Aplica estas directivas en el **servidor de tu aplicación**. Los servidores de Facephi ya operan con CORS; no hace falta replicar estas cabeceras en ellos. {% 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; ``` | Directiva | Qué habilita | | -------------------- | ---------------------------------------------------------------------------------------------- | | `default-src 'self'` | Solo recursos del mismo origen por defecto | | `script-src` | Scripts propios, inicialización del SDK, `blob:` y recursos de `widget-components.facephi.pro` | | `media-src` | Captura y reproducción de cámara/micrófono (`blob:`) | | `worker-src` | Web Workers generados en memoria por el SDK (`blob:`) | | `connect-src` | APIs biométricas, licencias e Identity Platform | {% hint style="warning" %} Si aparece *"Refused to create a worker from 'blob:…'"*, añade `blob:` a `worker-src` (o `child-src` en navegadores antiguos). {% endhint %} **Cabeceras complementarias** (configurar en el mismo servidor o proxy): | Cabecera | Valor | | ------------------------------ | --------------------------------- | | `Permissions-Policy` | `camera=self, microphone=self` | | `Referrer-Policy` | `strict-origin-when-cross-origin` | | `X-Content-Type-Options` | `nosniff` | | `Cross-Origin-Embedder-Policy` | `require-corp` | | `Cross-Origin-Opener-Policy` | `same-origin` | | `Cross-Origin-Resource-Policy` | `same-origin` | Valida la configuración en staging antes de producción. Si solo necesitas habilitar la CDN del SDK: ```plaintext script-src 'self' https://sdk-web.facephi.pro; connect-src 'self' https://sdk-web.facephi.pro; ``` *** ## Integración en aplicaciones nativas mediante WebView * Puedes utilizar el SDK dentro de una aplicación nativa a través de un WebView usando la integración del sitio web de tu proveedor de SDK de Facephi. Recomendamos personalizar el User-Agent de tu WebView añadiendo un token personalizado en lugar de reemplazar completamente el UA. #### Ejemplos de User-Agent * ❌ Ejemplo incorrecto: Código ``` sdkwebview ``` * ✅ Ejemplo correcto (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 ``` * ✅ Ejemplo correcto (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 * El User-Agent base puede reflejar el dispositivo/SO mínimo compatible; el último token debe ser `sdkwebview`. * Para aplicaciones iOS desarrolladas con Swift y Storyboards, habilita la reproducción en línea en WKWebView (Inline Playback / `allowsInlineMediaPlayback = true`). *** ## Guía de Configuración de Proxy Esta guía proporciona ejemplos listos para usar para un proxy de reenvío (forward proxy). El ejemplo se realizará con Nginx, pero se puede hacer con la tecnología de su elección. ### Tabla de Rutas
EndpointProtocolURL
/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
El proxy debe eliminar la ruta base y reenviar la solicitud al endpoint de destino, conservando la ruta URL restante. {% hint style="info" %} Facephi se encargará de ofrecer las urls necesarias en cada caso. {% endhint %} ### Servicio de Licencias Este servicio de licencias requiere que el motor HTTP actúe como un proxy de reenvío hacia un backend HTTPS externo, estableciendo el SNI correcto para el servidor de destino y reenviando los encabezados de solicitud originales mientras reemplaza el encabezado Host con el nombre de host del servidor de destino. Será responsabilidad del integrador emitir las 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 los encabezados CORS del 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 solo desde 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; # Manejo del preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` *** ### Servicio de Seguimiento (Tracking) Este servicio de seguimiento requiere que el motor HTTP actúe como un proxy de reenvío hacia un backend HTTPS externo, estableciendo el SNI correcto para el servidor de destino y reenviando los encabezados de solicitud originales mientras reemplaza el encabezado Host con el nombre de host del servidor de destino. Será responsabilidad del integrador emitir las 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 los encabezados CORS del 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: Ajustar el origen según su 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; } } ``` *** ### Servicio QR Este servicio QR requiere que el motor HTTP actúe como un proxy de reenvío hacia un backend WebSocket externo, estableciendo el SNI correcto para el servidor de destino y reenviando los encabezados de proxy esenciales mientras reemplaza el encabezado Host con el nombre de host del servidor de destino. El motor debe configurarse para admitir las actualizaciones de protocolo HTTP/1.1 conservando los encabezados Upgrade y Connection para habilitar la conectividad WebSocket. La política CORS debe ser definida por el integrador de acuerdo con sus requisitos de seguridad, y el proxy debe exponer encabezados de respuesta específicos como Content-Length y Content-Range para permitir el acceso del lado del cliente a esta información. ```nginx location /qr { proxy_pass https://sdk-web-services.facephi.pro/; # Configuración específica de WebSocket proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Encabezados estándar 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` es obligatorio * Los encabezados `Upgrade` y `Connection` son necesarios para el *handshake* *** ### Servicio de grabación de vídeo Este servicio de grabación de vídeo requiere que el motor HTTP actúe como proxy inverso hacia un backend WebSocket externo para identificación por vídeo en tiempo real. El motor debe configurarse para soportar actualizaciones de protocolo HTTP/1.1 conservando las cabeceras Upgrade y Connection para habilitar la conectividad WebSocket. Se configuran timeouts ampliados para mantener conexiones persistentes durante las sesiones de vídeo. La política CORS debe definirla el integrador según sus requisitos de seguridad. ```nginx location /identification { proxy_pass https://video-identification.eu.idv-suite.com; proxy_ssl_server_name on; # Configuración específica para WebSocket proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Cabeceras estándar 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 (mantener la conexión activa) 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; # Manejo de preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` **Requisitos de WebSocket:** * `proxy_http_version 1.1` es obligatorio * Las cabeceras `Upgrade` y `Connection` son necesarias para el handshake *** ### Servicio de recursos Este servicio de recursos requiere que el motor HTTP actúe como proxy inverso hacia un backend HTTPS externo, estableciendo el SNI correcto para el servidor de destino y reenviando las cabeceras originales de la petición, sustituyendo la cabecera Host por el nombre de host del servidor de destino. Será responsabilidad del integrador definir las 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 cabeceras CORS del 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: ajusta el origen según tu 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; } } ``` *** ### Servicio de autenticación API Este servicio de autenticación requiere que el motor HTTP actúe como proxy inverso hacia un backend HTTPS externo, estableciendo el SNI correcto para el servidor de destino y reenviando las cabeceras originales de la petición, sustituyendo la cabecera Host por el nombre de host del servidor de destino. Será responsabilidad del integrador definir las 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 cabeceras CORS del 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 únicamente desde 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; # Manejo de preflight OPTIONS if ($request_method = OPTIONS) { return 204; } } ``` *** ## Notas de Configuración **🔀 Comportamiento de `proxy_pass`** La barra inclinada al final (`trailing slash`) es importante: ```nginx # CON barra inclinada al final: reescribe la ruta location /api { proxy_pass https://backend.com/; # /api/users -> https://backend.com/users } # SIN barra inclinada al final: conserva la ruta completa location /api { proxy_pass https://backend.com; # /api/users -> https://backend.com/api/users } ``` **🌐 CORS** * Ajuste `Access-Control-Allow-Origin` a su dominio específico. * Puede usar `*` en desarrollo, pero NUNCA en producción con credenciales. * `proxy_hide_header` previene conflictos cuando el backend ya envía encabezados CORS. **📝 Encabezados Comunes** * `proxy_set_header Host $host;` # Dominio solicitado * `proxy_set_header X-Real-IP $remote_addr;` # IP del cliente * `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;` # Cadena de IP * `proxy_set_header X-Forwarded-Proto $scheme;` # http o https *** ## Comandos útiles Validar la configuración `nginx -t` Recargar la configuración (sin tiempo de inactividad) `nginx -s reload` Ver los logs de error `tail -f /var/log/nginx/error.log` Ver los logs de acceso `tail -f /var/log/nginx/access.log` Reiniciar Nginx `systemctl restart nginx` `# o` `service nginx restart` *** ## Próximos pasos * Configura los Componentes y módulos según tus necesidades. * Explora los [Ejemplos de integración](/productos/landing/ejemplos-de-integracion.md). * Revisa los apartados específicos de cada módulo como [Selphi](/sdks/sdk-web/componentes/selphi-biometria-facial.md), [SelphID](/sdks/sdk-web/componentes/selphid-documentos.md) o [Video Recording](/sdks/sdk-web/componentes/video-recording-video-grabacion.md).