Requisitos
Asegúrate de cumplir los siguientes requisitos antes de incrustar el iframe.
Token de iframe
Los tokens de iframe son gestionados por el equipo de Heuristik. Cada token está asociado con:
- Un tenant — la organización propietaria de la integración
- Una URL permitida — el origen donde se permite cargar el iframe
Para obtener un token, contacta a tu representante de Heuristik y proporciona el dominio donde se incrustará el iframe. Los tokens son permanentes — no caducan y no necesitan ser rotados.
Un solo token autoriza un origen específico. Si necesitas incrustar el iframe en múltiples dominios (ej. producción y staging), solicita un token separado para cada uno. Para revocar el acceso, contacta a tu representante de Heuristik.
Código de región
El código de región indica la región a la cual pertenece el usuario geográficamente y donde sus datos son almacenados.
Los códigos de regiones disponibles actualmente son los siguientes:
| Código región | Zona |
|---|---|
eu | Europa |
us | América |
Para saber cuál es el código de región que te corresponde, contacta con tu representante de Heuristik y proporciona el dominio en donde se incrustará el iframe.
Un código de región erróneo podría impedir la correcta autenticación del usuario al no existir en la región seleccionada; así como inhabilitar la carga del iframe aunque el token fuese válido.
Parámetro de URL
El iframe acepta un único parámetro de consulta:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
tokenIframe | string | Sí | Token de autenticación proporcionado por Heuristik |
regionCode | string | Sí | Código de región proporcionado por Heuristik |
https://iframe.heuristik.com?tokenIframe=YOUR_TOKEN®ionCode=YOUR_REGION_CODE
No existen parámetros opcionales para idioma, tema o personalización visual. La UI del iframe es fija.
Hardware y driver
El Iframe de Heuristik se comunica con el escáner de huellas a través de una conexión WebSocket local:
ws://127.0.0.1:2794/hk-reader
El driver local debe estar instalado y en ejecución en la estación de trabajo antes de que el iframe pueda realizar escaneos de huellas. Sin él, la conexión con el escáner fallará.
El driver local es obligatorio. Se ejecuta como un servicio local y expone el endpoint WebSocket al que se conecta el iframe. Contacta a tu representante de Heuristik para los paquetes de instalación del driver.
Certificado de seguridad
El iframe se ejecuta mediante conexión segura HTTPS. Por ello, para evitar problemas por parte del navegador derivados de contenido mixto (http-https); es preciso que la web contenedora disponag también de un certificado válido para poder ser cargada mediante el protocolo https.
Delegación de permisos
Además de contar con el driver instalado, para que la comunicación entre el iframe y el driver sea posible, es necesario habilitar el permiso de 'Aplicaciones en dispositivo' en versiones de Chrome +147 debido a una nueva regla de seguridad añadida en dicha versión.
También es recomendable tener activado y delegado el permiso para el portapapeles, a fin de poder capturar fácilmente la información interesada con los botones proporcionados para ello.
Además de habilitar en el navegador estas opciones, hay que realizar una delegación de permisos al iframe en la carga del mismo mediante allow="local-network-access; clipboard-write".
Cookies de terceros
El iframe se ejecuta en iframe.heuristik.com mientras tu aplicación se ejecuta en un origen diferente. El iframe necesita cookies de terceros para la gestión de sesión.
Si las cookies están bloqueadas, el iframe lo detecta y muestra una alerta localizada indicando al usuario que las habilite.
Los navegadores modernos bloquean cada vez más las cookies de terceros por defecto. Asegúrate de que los navegadores de tus usuarios permitan cookies de iframe.heuristik.com, o añádelo a la lista de permitidos en la configuración del navegador o políticas de grupo.
Estrategias de mitigación
- Configuración del navegador — añadir
iframe.heuristik.coma la lista de cookies de terceros permitidas - Política empresarial — desplegar políticas de navegador vía MDM/GPO para pre-autorizar el dominio
- Guía al usuario — mostrar instrucciones a los usuarios si la detección de cookies falla
Compatibilidad con navegadores
El iframe utiliza APIs web estándar con amplio soporte. La siguiente tabla muestra las versiones mínimas de navegador donde cada tecnología requerida tiene soporte completo:
| Tecnología | Chrome | Edge | Firefox |
|---|---|---|---|
postMessage | 2+ | 12+ | 3+ |
WebSocket | 16+ | 12+ | 11+ |
| Cookies de terceros | Permitidas por defecto | Permitidas (modo Equilibrado) | Particionadas por defecto (TCP) |
Versiones mínimas recomendadas
| Navegador | Recomendada | Configuración de cookies |
|---|---|---|
| Chrome | 80+ | No necesaria — las cookies de terceros están permitidas por defecto. Los usuarios pueden bloquearlas manualmente en chrome://settings/cookies. |
| Edge | 80+ | No necesaria — el modo Equilibrado (por defecto) permite cookies de terceros de dominios no rastreadores. |
| Firefox | 102+ | No necesaria en la mayoría de casos — Total Cookie Protection (por defecto desde Firefox 102) particiona las cookies por sitio pero no las bloquea. La sesión del iframe funciona dentro de cada sitio integrador. En modo ETP Estricto, pueden aplicarse restricciones adicionales. |
- Chrome y Edge — funcionan sin configuración adicional
- Firefox — funciona con TCP por defecto; las cookies se particionan por sitio pero la sesión del iframe funciona correctamente dentro de cada sitio integrador