For the complete documentation index, see llms.txt. This page is also available as Markdown.

Additional configuration

Configuration guides for implementations in special environments.

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

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


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

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.

Recommended policy:

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

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:


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

  • ✅ Correct example (Android):

    Code

  • ✅ Correct example (iOS):

    Code

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

Endpoint
Protocol
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

The proxy must remove the base path and forward the request to the destination endpoint, preserving the remaining URL path.

Facephi will be responsible for providing the necessary URLs in each case.

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.


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.


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.

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.

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.


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.


Configuration Notes

🔀 Behavior of proxy_pass

The trailing slash (trailing slash) is important:

🌐 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

Last updated