> 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-en/sdks/sdk-web/introduccion/configuracion-adicional.md). # Additional configuration ## Preloading Selphi and SelphID resources The package `@facephi/sdk-web-wc` exports the utilities `generateSelphiBrowserCache` and `generateSelphIDBrowserCache` to download the resources of the Selphi and SelphID engines in the browser **before** that `` is mounted in the DOM. If called in advance, they can reduce the perceived loading time when the user starts the biometric flow, since the widget assets will already be available in the browser cache. They must be called **before** after integrating the SDK Provider into the page. If the provider is already in the DOM, this step provides no benefit. ```javascript import { generateSelphiBrowserCache, generateSelphIDBrowserCache, } from '@facephi/sdk-web-wc'; // Download resources before mounting the SDK Provider await generateSelphiBrowserCache(process.env.FACEPHI_SDK_APIKEY); await generateSelphIDBrowserCache(process.env.FACEPHI_SDK_APIKEY); ``` Parameters: * `apiKey` (`string`): ApiKey with license for the corresponding widget. * `engineLocation` (`string`, optional): Custom path for the engine resources. For more details, see the documentation for each utility in [generateSelphiBrowserCache](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphibrowsercache.md) and [generateSelphIDBrowserCache](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphidbrowsercache.md). *** ## Content Security Policy (CSP) If your application uses strict CSP headers, you must explicitly allow the origins that the SDK Web and the biometric widgets need (scripts, workers, media and APIs). {% hint style="info" %} Apply these directives on the **server of your application**. Facephi servers already operate with CORS; there is no need to replicate these headers on them. {% endhint %} **Recommended policy:** ```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; ``` | Directive | What it enables | | -------------------- | ------------------------------------------------------------------------------------------- | | `default-src 'self'` | Same-origin resources only by default | | `script-src` | Own scripts, SDK initialization, `blob:` and resources from `widget-components.facephi.pro` | | `media-src` | Camera/microphone capture and playback (`blob:`) | | `worker-src` | Web Workers generated in memory by the SDK (`blob:`) | | `connect-src` | Biometric APIs, licenses, and Identity Platform | {% hint style="warning" %} If it appears *"Refused to create a worker from 'blob:…'"*, add `blob:` to `worker-src` (or `child-src` in older browsers). {% endhint %} **Additional headers** (configure on the same server or proxy): | Header | Value | | ------------------------------ | --------------------------------- | | `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` | Validate the configuration in staging before production. If you only need to enable the SDK CDN: ```plaintext script-src 'self' https://sdk-web.facephi.pro; connect-src 'self' https://sdk-web.facephi.pro; ``` *** ## Integration in native applications via WebView * You can use the SDK within a native application through a WebView using the website integration of your Facephi SDK provider. We recommend customizing the User-Agent of your WebView by adding a custom token instead of completely replacing the UA. #### User-Agent examples * ❌ Incorrect example: Code ``` sdkwebview ``` * ✅ Correct example (Android): Code ``` Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/115.0.0.0 Mobile Safari/537.36 sdkwebview ``` * ✅ Correct example (iOS): Code ``` Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 como Mac OS X) AppleWebKit/605.1.15 (KHTML, como Gecko) Mobile/15E148 sdkwebview ``` #### Notes * The base User-Agent can reflect the minimum compatible device/OS; the last token must be `sdkwebview`. * For iOS applications developed with Swift and Storyboards, enable inline playback in WKWebView (Inline Playback / `allowsInlineMediaPlayback = true`). *** ## Proxy Configuration Guide This guide provides ready-to-use examples for a forward proxy. The example will be done with Nginx, but it can be done with the technology of your choice. ### Route Table
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
The proxy must remove the base path and forward the request to the destination endpoint, preserving the remaining URL path. {% hint style="info" %} Facephi will be responsible for providing the necessary URLs in each case. {% endhint %} ### License Service This licensing service requires the HTTP engine to act as a forward proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers while replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to issue the CORS policies. ```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; # Hide backend CORS headers to avoid duplicates 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 controlled only from 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; # Handling OPTIONS preflight if ($request_method = OPTIONS) { return 204; } } ``` *** ### Tracking Service (Tracking) This tracking service requires the HTTP engine to act as a forward proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers while replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to issue the CORS policies. ```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; # Hide backend CORS headers (avoid duplicates) 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: Adjust the origin according to your 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; } } ``` *** ### QR Service This QR service requires the HTTP engine to act as a forward proxy to an external WebSocket backend, setting the correct SNI for the destination server and forwarding the essential proxy headers while replacing the Host header with the destination server's hostname. The engine must be configured to support HTTP/1.1 protocol upgrades, preserving the Upgrade and Connection headers to enable WebSocket connectivity. CORS policy must be defined by the integrator according to their security requirements, and the proxy must expose specific response headers such as Content-Length and Content-Range to allow client-side access to this information. ```nginx location /qr { proxy_pass https://sdk-web-services.facephi.pro/; # Specific WebSocket configuration proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Standard headers 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 for WebSockets (optional) 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; } ``` WebSocket requirements: * `proxy_http_version 1.1` is mandatory * The headers `Upgrade` and `Connection` are necessary for the *handshake* *** ### Video Recording Service This video recording service requires the HTTP engine to act as a reverse proxy to an external WebSocket backend for real-time video identification. The engine must be configured to support HTTP/1.1 protocol upgrades, preserving the Upgrade and Connection headers to enable WebSocket connectivity. Extended timeouts are configured to keep persistent connections alive during video sessions. The CORS policy must be defined by the integrator according to their security requirements. ```nginx location /identification { proxy_pass https://video-identification.eu.idv-suite.com; proxy_ssl_server_name on; # Specific WebSocket configuration proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Standard headers 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; # WebSocket timeout (keep the connection alive) proxy_read_timeout 86400s; proxy_send_timeout 86400s; # CORS for 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; # Handling OPTIONS preflight if ($request_method = OPTIONS) { return 204; } } ``` **WebSocket requirements:** * `proxy_http_version 1.1` is mandatory * The headers `Upgrade` and `Connection` are necessary for the handshake *** ### Resources Service This resources service requires the HTTP engine to act as a reverse proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers, replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to define the CORS policies. ```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/; # Hide backend CORS headers (avoid duplicates) 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: adjust the origin according to your 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; } } ``` *** ### API Authentication Service This authentication service requires the HTTP engine to act as a reverse proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers, replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to define the CORS policies. ```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; # Hide backend CORS headers to avoid duplicates 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 controlled only from 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; # Handling OPTIONS preflight if ($request_method = OPTIONS) { return 204; } } ``` *** ## Configuration Notes **🔀 Behavior of `proxy_pass`** The trailing slash (`trailing slash`) is important: ```nginx # WITH trailing slash: rewrites the path location /api { proxy_pass https://backend.com/; # /api/users -> https://backend.com/users } # WITHOUT trailing slash: preserves the full path location /api { proxy_pass https://backend.com; # /api/users -> https://backend.com/api/users } ``` **🌐 CORS** * Adjustment `Access-Control-Allow-Origin` to your specific domain. * You can use `*` in development, but NEVER in production with credentials. * `proxy_hide_header` prevents conflicts when the backend already sends CORS headers. **📝 Common Headers** * `proxy_set_header Host $host;` # Requested domain * `proxy_set_header X-Real-IP $remote_addr;` # Client IP * `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;` # IP chain * `proxy_set_header X-Forwarded-Proto $scheme;` # http or https *** ## Useful commands Validate the configuration `nginx -t` Reload the configuration (without downtime) `nginx -s reload` View the error logs `tail -f /var/log/nginx/error.log` View the access logs `tail -f /var/log/nginx/access.log` Restart Nginx `systemctl restart nginx` `# or` `service nginx restart` *** ## Next steps * Configure the Components and modules according to your needs. * Explore the [Integration examples](/docs.facephi-en/products/landing/ejemplos-de-integracion.md). * Review the specific sections of each module such as [Selphi](/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial.md), [SelphID](/docs.facephi-en/sdks/sdk-web/componentes/selphid-documentos.md) or [Video Recording](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion.md).