> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heretic.quest/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and Configure the Heretic Collector for Your Site

> Add @heretic-hq/collector to your site. The collector measures each visitor's session and returns a session ID you pass to the explain endpoint.

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](https://heretic.quest/dashboard/keys)

## Installation

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @heretic-hq/collector
  ```

  ```bash yarn theme={null}
  yarn add @heretic-hq/collector
  ```

  ```bash pnpm theme={null}
  pnpm add @heretic-hq/collector
  ```
</CodeGroup>

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

```ts theme={null}
import { Collector } from '@heretic-hq/collector';

const collector = new Collector({
  apiKey: 'hrtc_live_xxxxxxxxxxxxxxxxxxxx', // your key from the dashboard
});

const sessionId = await collector.collect();

// Forward sessionId to your server — e.g. in a request header or POST body.
await fetch('/api/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ hereticSession: sessionId }),
});
```

<Tip>
  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.
</Tip>

## Configuration Options

<ParamField query="apiKey" type="string" required>
  Your Heretic API key. Retrieve it from [heretic.quest/dashboard/keys](https://heretic.quest/dashboard/keys). Keep this key out of public source control — consider injecting it via an environment variable at build time.
</ParamField>

<ParamField query="render" type="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.
</ParamField>

<Tip>
  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.
</Tip>

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


## Related topics

- [Heretic API Keys: Collector Setup and Explain Endpoint](/dashboard/api-keys.md)
- [Heretic Quick Start: Collect Sessions and Read Verdicts](/quickstart.md)
- [Heretic Dashboard: Manage Sites, Keys, and Verdicts](/dashboard/overview.md)
- [Heretic FAQ: Integration, Verdicts, Privacy, and Access](/reference/faq.md)
- [Heretic: Physics-Based Browser Intelligence Platform](/introduction.md)