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"
  width="100%"
  height="600"
  frameborder="0"
  title="Heuristik Identification"
></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.

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"
    width="100%"
    height="600"
    frameborder="0"
    title="Heuristik Identification"
  ></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