Opt-out and excluding traffic

Traffic can be kept out at two places: in the browser, where the script sends nothing (opt-out, ?pilotfox_ignore, Global Privacy Control, data-skip), and on the server, where PilotFox drops what it receives (allowed hostnames, exclusions, the bot filter).

Your own visitsCopy Anchor Link

• ?pilotfox_ignore=true is read when the script starts and stored in the browser's localStorage under its own key, pilotfox:ignore. From then on the script sends nothing from that browser, in every tab, until it is undone.
• ?pilotfox_ignore=false removes only that flag. It never undoes optOut(): anyone can put the parameter in a link to your site, and an opt-out may be a visitor's own choice. pilotfox.optIn() removes both.
• Browser storage belongs to one origin: https://example.com and https://www.example.com (or http://localhost:3000) each need their own flag. Clearing the site's data removes it.
• The page opened with ?pilotfox_ignore=false is recorded with that parameter in its address. To keep it out of the stored query strings, add pilotfox_ignore to Strip parameters (Site settings → Privacy & identity).

Opt-out for visitorsCopy Anchor Link

optOut() and optIn() are meant for your own consent banner or privacy settings:

// The visitor declines analytics:
window.pilotfox?.optOut();

// The visitor accepts it again:
window.pilotfox?.optIn();

While a browser is opted out:

• no pageviews, events or identify calls are sent, in any open tab of the site, and identify stores no user id;
• a session recording stops at once, in every open tab of the site, and what was recorded but not yet sent is discarded;
• the script still loads the site's settings (GET /api/c/SITE_ID, without credentials) on each page load.

The choice is stored in localStorage (pilotfox:optout) and remembered until optIn(). If storage is blocked, it lasts for the page only. optOut() called before the site's settings have arrived is never dropped, whatever else is waiting (see the queue). After optIn(), tracking resumes at once, and session replay (in a tab that is recorded) from the next page load or route change.

To keep the script from sending anything on a page without storing a choice, set window.__PILOTFOX_OPTOUT__ = true before (or after) the script loads; the script checks it before every request.

With a custom data-namespace, the storage keys start with that name instead of pilotfox (analytics:optout); the URL parameter stays pilotfox_ignore.

Global Privacy ControlCopy Anchor Link

Browsers that send the Global Privacy Control signal (navigator.globalPrivacyControl === true) are not tracked: no events, no identify, no recording. This is on by default, also when the site's settings cannot be loaded; Site settings → Privacy & identity → Respect Global Privacy Control can turn it off. PilotFox reads the GPC signal, not the older Do Not Track header.

Excluding traffic on the serverCopy Anchor Link

What the server drops is never stored. It does not change events already stored.

Allowed hostnamesCopy Anchor Link

Site settings → Privacy & identity → Allowed hostnames: when the list is not empty, events whose page is on any other host name are dropped, for example from a staging copy that still carries the tag.

• example.com matches that host name only.
• *.example.com matches any subdomain of example.com (shop.example.com, eu.shop.example.com), never example.com itself: list both if you need both.
• Up to 50 entries, compared without regard to case.

ExclusionsCopy Anchor Link

Site settings → Exclusions drops traffic that matches any rule:

Path exclusions are globs only: unlike data-skip, they take no re: regular expressions (the settings page refuses them, and the server ignores one saved through the API for events). Behind a first-party proxy, the IP, country and network rules apply to the visitor's address that your proxy forwards.

The IP, country, network and user-agent rules drop identify requests too; Allowed hostnames and the path rules do not, as an identify request carries no page address.

BotsCopy Anchor Link

Bot traffic is dropped by default and shown in the Bots report instead, with the reason and, for AI crawlers and assistants, the operator. PilotFox checks the user agent, the request headers, signals from the browser (such as navigator.webdriver, which browser automation sets), the network and the request rate. Site settings → Bots → Block bot traffic off keeps them in your reports, marked as device type bot. See Bots for what is stored about them.

Tagged linksCopy Anchor Link

Visits from posts on X, LinkedIn, Medium or a newsletter often arrive without a referrer and count as Direct. Site settings → Link builder adds campaign (utm_*) or affiliate (?ref=) parameters to a link of your site, so those visits are reported under their campaign.