Configuración adicional

Guías de configuración para implementaciones en entornos especiales.

📱 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

Endpoint	Protocolo	URL
/licensing	https	https://license.identity-platform.io/
/tracking	https	https://api.identity-platform.io/ *
/qr	wss	https://sdk-web-services.facephi.pro/

El proxy debe eliminar la ruta base y reenviar la solicitud al endpoint de destino, conservando la ruta URL restante.

Para usar el endpoint de seguimiento (tracking), debes solicitar al equipo de soporte de Facephi la URL correspondiente al entorno utilizado.

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.

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.

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.

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

---

Notas de Configuración

🔀 Comportamiento de proxy_pass

La barra inclinada al final (trailing slash) es importante:

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

• Revisa los apartados específicos de cada módulo como Selphi, SelphID o Video Recording.