Skip to main content

Iframe Integration

This guide walks you through embedding the Heuristik Iframe. Make sure you have completed all requirements before starting.

Step 1 — Embed the iframe​

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>
No camera or microphone needed

Unlike webcam-based verification, the Heuristik Iframe uses a USB-connected fingerprint scanner. You do not need allow="camera; microphone" on the iframe, but Yes it is necessary to delegate access to local networks for communication with the sensor, and to the clipboard for the correct operation of the copy buttons (allow="local-network-access; clipboard-write").

Step 2 — User flow inside the iframe​

Once the iframe loads and validates the token, the following flow occurs inside:

If the fingerprint scanner or driver is not detected, the iframe shows a connection error screen with a "Try again" button. The user cannot proceed until the scanner and driver are available. Once detected, the flow continues normally.

The entire identification flow — staff authentication, fingerprint scanning, and patient lookup — happens within the iframe. Your application only needs to listen for the result.

Step 3 — Receive results via postMessage​

When the identification or registration completes, the iframe sends a message to the parent window via postMessage. There are two distinct events:

Identification event​

Sent when a fingerprint matches an existing patient in the system. Your application receives the patient's HHID to look up their records.

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

Registration event​

Sent when a fingerprint does not match any existing patient and a new record is created. Your application receives the newly assigned HHID.

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

Message fields​

FieldTypeDescription
HHIDstringThe Heuristik patient identifier
isNewbooleantrue if the patient was just registered, false if already existed

Listener implementation​

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

  const { HHID, isNew } = event.data;

  if (isNew) {
    // New patient registered — create record in your system
    console.log('New patient registered:', HHID);
  } else {
    // Existing patient identified — fetch their records
    console.log('Patient identified:', HHID);
  }
});
Security

Always validate event.origin against https://iframe.heuristik.com before processing messages. Never trust messages from unknown origins.

Live test environment​

Heuristik provides a test page where you can see the iframe integration in action:

You can inspect the source code of the test page to see a working implementation: view-source:https://testiframe.heuristik.com/

Complete example​

A minimal end-to-end integration in plain HTML, aligned with the implementation used in the live test environment:

complete-example.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Heuristik Iframe Example</title>
</head>
<body>
  <h1>Patient Identification</h1>

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

  <p>HHID: <span id="hhid-answer">—</span></p>
  <p>New patient: <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>

Key points about this implementation:

  • Origin validation — originAllowed is checked against event.origin to reject messages from unknown sources
  • HHID — the unique patient identifier returned by Heuristik
  • isNew — distinguishes between identification (false) and registration (true) events
  • No polling — the iframe pushes results to your page; no need to poll or query an API