Integración del Iframe

Esta guía te acompaña paso a paso en la integración del Iframe de Heuristik. Asegúrate de haber completado todos los requisitos antes de comenzar.

Paso 1 — Incrustar el iframe

HTML

index.html

<iframe
  id="heuristik-frame"
  src="https://iframe.heuristik.com?tokenIframe=YOUR_TOKEN&regionCode=YOUR_REGION_CODE"
  width="100%"
  height="600"
  frameborder="0"
  title="Heuristik Identification"
  allow="local-network-access; clipboard-write"
></iframe>

React

IdentificationFrame.tsx

interface Props {
  tokenIframe: string;
  regionCode: string;
}

export function IdentificationFrame({ tokenIframe, regionCode }: Props) {
  return (
    <iframe
      src={`https://iframe.heuristik.com?tokenIframe=${tokenIframe}&regionCode=${regionCode}`}
      width="100%"
      height={600}
      frameBorder={0}
      title="Heuristik Identification"
      allow="local-network-access; clipboard-write"
    />
  );
}

Vue

IdentificationFrame.vue

<script setup lang="ts">
defineProps<{ tokenIframe: string, regionCode: string }>();
</script>

<template>
  <iframe
    :src="`https://iframe.heuristik.com?tokenIframe=${tokenIframe}&regionCode=${regionCode}`"
    width="100%"
    height="600"
    frameborder="0"
    title="Heuristik Identification"
    allow="local-network-access; clipboard-write"
  />
</template>

No se necesita cámara ni micrófono

A diferencia de la verificación basada en webcam, el Iframe de Heuristik utiliza un escáner de huellas conectado por USB. No necesitas allow="camera; microphone" en el iframe; pero Sí es necesario delegar el acceso a redes locales para la comunicación con el sensor, y el de portapapeles para el correcto funcionamiento de los botones de copiado (allow="local-network-access; clipboard-write").

Paso 2 — Flujo del usuario dentro del iframe

Una vez que el iframe carga y valida el token, el siguiente flujo ocurre en su interior:

Si el escáner de huellas o el driver no se detectan, el iframe muestra una pantalla de error de conexión con un botón "Reintentar". El usuario no puede continuar hasta que el escáner y el driver estén disponibles.

Todo el flujo de identificación — autenticación del personal, escaneo de huella y búsqueda del paciente — ocurre dentro del iframe. Tu aplicación solo necesita escuchar el resultado.

Paso 3 — Recibir resultados vía postMessage

Cuando la identificación o el registro se completa, el iframe envía un mensaje a la ventana padre mediante postMessage. Existen dos eventos diferenciados:

Evento de identificación

Se envía cuando una huella coincide con un paciente existente en el sistema. Tu aplicación recibe el HHID del paciente para consultar sus registros.

{ "HHID": "a1b2c3d4e5f6g7h8", "isNew": false }

Evento de registro

Se envía cuando una huella no coincide con ningún paciente existente y se crea un nuevo registro. Tu aplicación recibe el HHID recién asignado.

{ "HHID": "e5f6g7h8a1b2c3d4", "isNew": true }

Campos del mensaje

Campo	Tipo	Descripción
HHID	string	El identificador de paciente de Heuristik
isNew	boolean	true si el paciente fue recién registrado, false si ya existía

Implementación del listener

listener.js

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://iframe.heuristik.com') return;

  const { HHID, isNew } = event.data;

  if (isNew) {
    // Nuevo paciente registrado — crear registro en tu sistema
    console.log('Nuevo paciente registrado:', HHID);
  } else {
    // Paciente existente identificado — obtener sus registros
    console.log('Paciente identificado:', HHID);
  }
});

Seguridad

Siempre valida event.origin contra https://iframe.heuristik.com antes de procesar mensajes. Nunca confíes en mensajes de orígenes desconocidos.

Entorno de prueba en vivo

Heuristik proporciona una página de prueba donde puedes ver la integración del iframe en acción:

• Página de prueba: testiframe.heuristik.com

Puedes inspeccionar el código fuente de la página de prueba para ver una implementación funcional: view-source:https://testiframe.heuristik.com/

Ejemplo completo

Una integración mínima de extremo a extremo en HTML plano, alineada con la implementación usada en el entorno de prueba en vivo:

complete-example.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Ejemplo de Iframe de Heuristik</title>
</head>
<body>
  <h1>Identificación de pacientes</h1>

  <iframe
    id="heuristik-frame"
    src="https://iframe.heuristik.com?tokenIframe=YOUR_TOKEN&regionCode=YOUR_REGION_CODE"
    width="100%"
    height="600"
    frameborder="0"
    title="Identificación Heuristik"
    allow="local-network-access; clipboard-write"
  ></iframe>

  <p>HHID: <span id="hhid-answer">—</span></p>
  <p>Nuevo paciente: <span id="new-answer">—</span></p>

  <script>
    const originAllowed = 'https://iframe.heuristik.com';

    window.addEventListener('message', (event) => {
      if (event.origin !== originAllowed) return;

      const { HHID, isNew } = event.data;

      document.getElementById('hhid-answer').textContent = HHID;
      document.getElementById('new-answer').textContent = isNew ? 'Yes' : 'No';
    });
  </script>
</body>
</html>

Puntos clave de esta implementación:

• Validación de origen — originAllowed se verifica contra event.origin para rechazar mensajes de fuentes desconocidas
• HHID — el identificador único de paciente devuelto por Heuristik
• isNew — distingue entre eventos de identificación (false) y registro (true)
• Sin polling — el iframe envía los resultados a tu página; no es necesario hacer polling ni consultar una API