privacy-signals

Detect browser privacy opt-out signals: Do Not Track and Global Privacy Control.

Use it to gate analytics, error reporting, or any other tracking on the user's browser-level opt-out, without sprinkling non-standard navigator property checks through your code.

• Checks every place browsers have exposed these signals: navigator.doNotTrack, window.doNotTrack, navigator.msDoNotTrack, and globalPrivacyControl on both navigator and window
• Handles the legacy "yes" value some older browsers report alongside the modern "1"
• Safe outside the browser: returns null instead of throwing when there is no browsing context to read
• Zero dependencies, ESM, TypeScript types included

Install

pnpm add privacy-signals
# or: npm install privacy-signals

Usage

import { isTrackingOptedOut } from "privacy-signals";

if (isTrackingOptedOut() === false) {
  initAnalytics();
}

Compare against false rather than writing if (!isTrackingOptedOut()). The unknown case is null, which is falsy, so the negation form would start tracking during server-side rendering.

When you need to know which signal fired, read them separately:

import { getPrivacySignals } from "privacy-signals";

const signals = getPrivacySignals();
if (signals === null) {
  // Unknown: no browsing context to read, e.g. server-side rendering.
  // Do not treat this as "no opt-out"; re-check on the client, where
  // the signal actually lives.
} else if (signals.globalPrivacyControl) {
  // GPC carries legal weight under CCPA/CPRA; handle the opt-out request.
}

Avoid signals?.globalPrivacyControl as a bare condition: it collapses null into the no-opt-out path, the same trap as !isTrackingOptedOut() above.

API

isTrackingOptedOut(): boolean | null

| Result | Meaning | | ------- | ------------------------------------------------------------------------------------------------------ | | true | The user has opted out, via Do Not Track or Global Privacy Control. | | false | The browser was readable and reported no opt-out, including an explicit opt-in (doNotTrack === "0"). | | null | The signals could not be read at all: not a browsing context, or reading threw. |

null is not consent. Decide deliberately what your app does with it: defer the call to the client where the real answer lives, or treat unknown as opted out if you want the conservative default.

Server runtimes — Node 21+, Deno, Bun, edge — define a minimal global navigator, so checking that navigator exists is not enough on its own; doing that alone would report false on the server and assert an opt-out that was never read. Server-side rendering returns null.

getPrivacySignals(): PrivacySignals | null

Reads the two signals separately, each normalized to a boolean:

type PrivacySignals = {
  doNotTrack: boolean;
  globalPrivacyControl: boolean;
};

Use this when the distinction matters. Global Privacy Control is a legal opt-out request under CCPA/CPRA; Do Not Track never carried that weight. Returns null in exactly the cases isTrackingOptedOut() does: no browsing context, or reading threw. isTrackingOptedOut() is just the OR of the two fields.

Workers

Web workers and service workers are supported. The GPC spec exposes the signal on WorkerNavigator as well as Navigator, deliberately covering dedicated, shared, and service workers, so a worker gets a real answer rather than null.

Outside a window, the check is whether navigator actually carries one of these properties, not whether the global scope looks worker-shaped. Cloudflare Workers and similar edge runtimes present a ServiceWorkerGlobalScope while giving navigator only userAgent and sendBeacon, so testing for the property itself is what tells a browser worker apart from an edge server. Those runtimes still return null.

A note on Do Not Track

Do Not Track was deprecated in 2018 and browsers have been dropping it, so navigator.doNotTrack is absent or always null in a growing share of them. Global Privacy Control is its replacement and the one that carries legal weight under CCPA/CPRA. This package keeps reading both, because a browser that still reports DNT is still telling you something, but treat GPC as the signal that matters.

License

MIT