Requirements
Ensure the following requirements are met before embedding the iframe.
Iframe token
Iframe tokens are managed by the Heuristik team. Each token is associated with:
- A tenant — the organization that owns the integration
- An allowed URL — the origin where the iframe is permitted to load
To obtain a token, contact your Heuristik representative and provide the domain where the iframe will be embedded. Tokens are permanent — they do not expire and do not need to be rotated.
A single token authorizes one specific origin. If you need to embed the iframe on multiple domains (e.g., production and staging), request a separate token for each. To revoke access, contact your Heuristik representative.
URL parameter
The iframe accepts a single query parameter:
| Parameter | Type | Required | Description |
|---|---|---|---|
tokenIframe | string | Yes | Authentication token provided by Heuristik |
https://iframe.heuristik.com?tokenIframe=YOUR_TOKEN
There are no optional parameters for locale, theme, or visual customization. The iframe UI is fixed.
Hardware and driver
The Heuristik Iframe communicates with the fingerprint scanner through a local WebSocket connection:
ws://127.0.0.1:2794/hk-reader
The local driver must be installed and running on the workstation before the iframe can perform fingerprint scans. Without it, the scanner connection will fail.
The local driver is mandatory. It runs as a local service and exposes the WebSocket endpoint that the iframe connects to. Contact your Heuristik representative for driver installation packages.
Third-party cookies
The iframe runs on iframe.heuristik.com while your application runs on a different origin. The iframe needs third-party cookies for session management.
If cookies are blocked, the iframe detects this and shows a localized alert prompting the user to enable them.
Modern browsers increasingly block third-party cookies by default. Ensure your users' browsers allow cookies from iframe.heuristik.com, or add it to the allowed list in browser/group policy settings.
Mitigation strategies
- Browser settings — add
iframe.heuristik.comto the third-party cookie allowlist - Enterprise policy — deploy browser policies via MDM/GPO to pre-allow the domain
- User guidance — display instructions to users if cookie detection fails
Browser compatibility
The iframe relies on standard web APIs with broad support. The table below lists the minimum browser versions where each required technology is fully supported:
| Technology | Chrome | Edge | Firefox |
|---|---|---|---|
postMessage | 2+ | 12+ | 3+ |
WebSocket | 16+ | 12+ | 11+ |
| Third-party cookies | Allowed by default | Allowed (Balanced mode) | Partitioned by default (TCP) |
Recommended minimum versions
| Browser | Recommended | Cookie configuration |
|---|---|---|
| Chrome | 80+ | Not needed — third-party cookies allowed by default. Users can block them manually via chrome://settings/cookies. |
| Edge | 80+ | Not needed — Balanced mode (default) allows third-party cookies from non-tracker domains. |
| Firefox | 102+ | Not needed in most cases — Total Cookie Protection (default since Firefox 102) partitions cookies per-site but does not block them. The iframe session works within each embedding site. In ETP Strict mode, additional restrictions may apply. |
- Chrome and Edge — work without additional configuration
- Firefox — works with TCP by default; cookies are partitioned per-site but the iframe session works correctly within each embedding site