Iframe Overview

The Heuristik Iframe embeds a fully hosted biometric identification UI into your application. It runs on iframe.heuristik.com and communicates results back to your page via postMessage.

How it works

Key characteristics

• Hosted UI — runs entirely on iframe.heuristik.com, no frontend code to build or maintain
• Hardware required — needs a fingerprint scanner connected via USB and the local driver running (both provided by Heuristik)
• Staff authentication — clinic staff log in inside the iframe before scanning
• Results via postMessage — the iframe sends { HHID: string, isNew: boolean } to the parent window
• Token-based access — a tokenIframe provided by Heuristik authorizes the integration
• Region code - a regionCode provided by Heuristik indicates the region to which the user data belongs
• Valid certificate - it is necessary to have a valid security certificate on the containing website in order to avoid mixed content (HTTP-HTTPS), since otherwise the browser blocks communication with the sensor.
• Permission Delegation - the iframe needs the 'Applications on device' permission to be enabled in the browser and this permission to be delegated to the iframe, for connection to the websocket for communication with the fingerprint sensor. Likewise, permission to be able to copy to the clipboard and for the buttons that facilitate copying must be delegated to work correctly.
• Third-party cookies required — the iframe needs cross-origin cookies for session management

When to use the Iframe

	Iframe	JavaScript SDK
Integration effort	Minimal — embed an <iframe> tag	Medium — install package, write code
UI customization	None — hosted UI as-is	Full control over UI
Hardware dependency	Fingerprint scanner + local driver	Fingerprint scanner + local driver
Authentication	Staff logs in inside the iframe	Your app handles auth via SDK
Result delivery	postMessage to parent window	Callback functions in your code
Best for	Quick integration with no frontend changes	Custom workflows and UI

When to choose the Iframe

Use the Iframe when you want the fastest integration path and don't need UI customization. If you need control over the identification flow or UI, use the JavaScript SDK instead.

Prerequisites

Before integrating the Iframe, ensure you meet all requirements. In summary:

1. Fingerprint scanner and local driver (both provided by Heuristik)
2. Iframe token (provided by Heuristik)
3. Region code (provided by Heuristik)
4. Valid certificate on the containing website to avoid mixed HTTP-HTTPS content
5. 'Apps on device' permission enabled and delegated to iframe
6. 'Clipboard' permission enabled and delegated to iframe
7. Third-party cookies enabled for iframe.heuristik.com