> 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

Configuration guides for deployments in special environments.

## Pre-checking the device

The package `@facephi/sdk-web-wc` exports `checkCapabilities` from the subpath `/capabilities.mjs` to check whether the device can run the biometric flow **before** mounting `<facephi-sdk-provider>`.

This is useful for routing the session to another device or business flow instead of letting the flow fail after it has started. It does not require `apiKey` and does not download any resources.

```javascript
import { checkCapabilities } from '@facephi/sdk-web-wc/capabilities.mjs';

const { camera, wasm, browser } = await checkCapabilities();
```

{% hint style="warning" %}
`camera` is a signal, not a guarantee: browsers that hide devices until permission is granted return `false` on a valid device. Use it as a soft condition, always offering a retry. `wasm` and `browser` are hard requirements.
{% endhint %}

For more details, see the [checkCapabilities](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/metodos/checkcapabilities.md).

***

## Preloading Selphi and SelphID resources

The package `@facephi/sdk-web-wc` exports the utilities `generateSelphiBrowserCache` and `generateSelphIDBrowserCache` to download Selphi and SelphID engine resources in the browser **before** the `<facephi-sdk-provider>` is mounted in the DOM.

Calling them in advance can reduce the perceived loading time when the user starts the biometric flow, as the widget assets will already be available in the browser cache.

They must be called **before** 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 licensed for the corresponding widget.
* `engineLocation` (`string`, optional): Custom path to the engine resources.

For more details, see the documentation for each utility at [generateSelphiBrowserCache](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/metodos/generateselphibrowsercache.md) and [generateSelphIDBrowserCache](https://docs.facephi.com/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 required by the SDK Web and biometric widgets (scripts, workers, media, and APIs).

{% hint style="info" %}
Apply these directives on your **application server**. Facephi servers already support CORS; you do not 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'` | Only same-origin resources by default                                                            |
| `script-src`         | Your 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 you see *"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 using WebView

{% hint style="warning" %}
If you use `antispoof` inside a WebView, review the memory considerations and known limitations in [`antispoof`](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial/propiedades/antispoof.md#consideraciones-en-webview).
{% endhint %}

* You can use the SDK within a native application through a WebView by using your Facephi SDK provider's website integration. We recommend customizing your WebView's User-Agent by adding a custom token instead of replacing the UA entirely.

#### User-Agent examples

* ❌ Incorrect example:

  Code

  ```
  sdkwebview
  ```
* ✅ Correct example (Android):

  Code

  ```
  Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Mobile Safari/537.36 sdkwebview
  ```
* ✅ Correct example (iOS):

  Code

  ```
  Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 sdkwebview
  ```

#### Notes

* The base User-Agent may reflect the minimum supported 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 uses Nginx, but you can use any technology of your choice.

### Routes Table

<table><thead><tr><th width="208.2109375">Endpoint</th><th width="123.9765625">Protocol</th><th>URL</th></tr></thead><tbody><tr><td><code>/licensing</code></td><td>https</td><td>https://license.identity-platform.io</td></tr><tr><td><code>/tracking</code></td><td>https</td><td>https://idv-ing-proxy.eu.idv-suite.com</td></tr><tr><td><code>/qr</code></td><td>wss</td><td>https://sdk-web-services.facephi.pro</td></tr><tr><td><code>/identification</code></td><td>wss</td><td>https://video-identification.eu.idv-suite.com</td></tr><tr><td><code>/resources</code></td><td>https</td><td>https://widget-components.facephi.pro/</td></tr><tr><td><code>/auth</code></td><td>https</td><td>https://idv-ing-proxy.eu.idv-suite.com</td></tr></tbody></table>

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 provide the necessary URLs for each case.
{% endhint %}

### Licensing 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. The integrator is responsible for issuing 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 the backend CORS headers to prevent 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 by 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;

    # Handle the OPTIONS preflight
    if ($request_method = OPTIONS) {
        return 204;
    }
}
```

***

### Tracking Service

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. The integrator is responsible for issuing 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 the backend CORS headers (prevent 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 to match 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 while preserving the Upgrade and Connection headers to enable WebSocket connectivity. The 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/;
    
    # WebSocket-specific 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 `Upgrade` and `Connection` are required 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 while preserving the Upgrade and Connection headers to enable WebSocket connectivity. Extended timeouts are configured to maintain persistent connections during video sessions. The integrator must define the CORS policy according to their security requirements.

```nginx
location /identification {
    proxy_pass https://video-identification.eu.idv-suite.com;
    proxy_ssl_server_name on;

    # WebSocket-specific 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;
    
    # OPTIONS preflight handling
    if ($request_method = OPTIONS) {
        return 204;
    }
}
```

**WebSocket requirements:**

* `proxy_http_version 1.1` is mandatory
* The `Upgrade` and `Connection` headers are required 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. The integrator is responsible for defining 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. The integrator is responsible for defining 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 by 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;

    # OPTIONS preflight handling
    if ($request_method = OPTIONS) {
        return 204;
    }
}
```

***

## Configuration Notes

**🔀 Behavior of `proxy_pass`**

The trailing slash (`trailing slash`) is important:

```nginx
# WITH a trailing slash: rewrites the path
location /api {
    proxy_pass https://backend.com/;
    # /api/users -> https://backend.com/users
}

# WITHOUT a trailing slash: preserves the full path
location /api {
    proxy_pass https://backend.com;
    # /api/users -> https://backend.com/api/users
}
```

**🌐 CORS**

* Set `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 (with no 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 to suit your needs.
* Explore the [Integration examples](https://docs.facephi.com/docs.facephi-en/products/landing/ejemplos-de-integracion.md).
* Review the specific sections for each module, such as [Selphi](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial.md), [SelphID](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/selphid-documentos.md) or [Video Recording](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion.md).

<br>
