Embed the Collector

In one sentence

Load the collector from your origin, call verify() with your edge URL and a session reference, and let it relay signals — then read the verdict on your backend.

This is step 1 of three. You'll also deploy the edge and fetch the verdict.

Mint a sessionRef first

On each page view where you want a verdict, have your backend mint an opaque, unguessable sessionRef (for example a random token) and make it available to the page. It correlates the browser's signal collection with the verdict your backend will later fetch. Keep it short-lived and treat it like a nonce.

Load and call the collector

You serve the collector from your own origin (see Collector package). Use whichever load method fits your stack.

ESM (bundler)

import { verify } from '@octetproof/collector';

await verify({
  apiUrl: 'https://yourapp.com/octet',   // your edge — see Deploy the Edge
  sessionRef: 'sess_abc123',             // the token your backend minted
});

<script> tag (global)

<script
  src="https://yourapp.com/static/octet-collector.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>
<script>
  octet.verify({ apiUrl: 'https://yourapp.com/octet', sessionRef: 'sess_abc123' });
</script>

verify() options

Option	Type	Notes
apiUrl	string (required)	Base URL of your edge. The collector posts to ${apiUrl}/v1/signals and opens a latency channel at ${apiUrl}/v1/ws.
sessionRef	string	The opaque token from your backend. Required if you want to fetch the verdict server-to-server.
wsUrl	string	Override the latency-channel URL. Defaults to the ws/wss equivalent of apiUrl + /v1/ws.
passiveOnly	boolean	Skip the active network measurements for a faster, lighter pass. Reduces confidence.
signal	AbortSignal	Abort an in-flight verify() (e.g. on route change).

Full reference: Collector API.

What verify() resolves with — and what not to do with it

verify() returns a promise that resolves when collection finishes. Do not use its result to make a security decision. Anything that happens in the browser is client-controlled and can be tampered with. The authoritative verdict comes from your backend, server-to-server.

Treat verify() as fire-and-forget from the page's perspective:

// Don't block the user on it; don't trust its return for policy.
verify({ apiUrl: 'https://yourapp.com/octet', sessionRef }).catch(() => {
  // network/collection failed — your backend's verdict fetch will simply be "pending"
});

Same-origin keeps it simple

Serving the collector and exposing the edge under your domain (e.g. yourapp.com/octet) keeps the whole flow first-party and avoids cross-origin complications. If your edge is on a different subdomain, you'll need CORS to allow it — the edge permits cross-origin calls, but same-origin is the cleaner default. See How It Works.

Where to go next

• Deploy the Edge. Stand up the apiUrl the collector posts to.
• Fetch the Verdict. Read the result on your backend.