Skip to main content
The Heretic collector runs client-side on your pages. It silently measures each visitor’s browser environment — network geometry, transport stack, rendering behavior, and more — then returns a short-lived session ID. You forward that ID to your backend and exchange it for a full verdict by calling the explain endpoint server-side. Nothing leaves the client except a compact identifier; all heavy analysis happens on Heretic’s edge.

Prerequisites

  • A Node.js project (front-end framework, plain HTML with a bundler, or a meta-framework like Next.js or Nuxt)
  • An API key from heretic.quest/dashboard/keys

Installation

Install @heretic-hq/collector with your preferred package manager.

Initialize the Collector

Import Collector, pass your API key, and call collect(). The call is asynchronous — it resolves once the collector has gathered enough evidence to issue a session ID.
Call collect() as early in the page lifecycle as possible. The collector works in the background; by the time the user performs any meaningful action, the session ID is typically already ready.

Configuration Options

string
required
Your Heretic API key. Retrieve it from heretic.quest/dashboard/keys. Keep this key out of public source control — consider injecting it via an environment variable at build time.
boolean
default:"true"
When true (the default), the collector includes device fingerprinting via render clustering, which compares how the browser rasterises a reference scene against known GPU/driver profiles. Set to false to disable this signal family and reduce the volume of data the collector gathers.
Setting render: false trades the render-clustering signal family for a lighter data footprint. This is a reasonable choice for privacy-sensitive deployments. All other measurement families — network geometry, transport stack, locale, and more — continue to run.

Privacy Characteristics

The Heretic collector sets no advertising identifiers and reads no cookies. The only thing it writes to browser storage is a short-lived note (approximately 15 minutes) recording which edge node answered the session — enough to route a follow-up call correctly, nothing more. After that window closes, the note expires automatically.