PilotFoxDocs
Getting started

Concepts and metrics

What PilotFox measures and how each number is defined: sessions, visitors, pageviews, bounce rate, durations and channels.

From a request to a visitor and a session

The tracking script sends one small request per pageview or event. Everything else happens on the server, for each request:

  1. Visitor. PilotFox derives a visitor id from a secret kept per site, the site, the visitor's IP address and the browser's user agent (with version numbers removed). No cookie or browser storage is involved, the IP address is not kept, and the same person gets unrelated ids on two sites. See Counting visitors without cookies.
  2. Session. The visitor's session continues while events keep arriving; it ends after 30 minutes without an event. The next event starts a new session. Identifying a user in the middle of a session does not start a new one.
  3. Enrichment. Location (from the IP address), browser, operating system and device (from the user agent), the referrer and its channel, and the campaign (utm_*) parameters of the page URL.
  4. Storage. The event is stored with those fields. Reports are computed from the stored events when you open them, so a filter or a new goal applies to past data too.

Requests the bot filter recognises are kept apart and shown in the Bots report instead (see Bots).

Users

When your site calls identify, PilotFox links the visitor to your user id. A session counts as that user's when any of its events carries the user id, or when its visitor was linked to the user; otherwise it counts as an anonymous visitor. So a user you identify counts once, across devices and browsers, and the earlier anonymous sessions of the same visitor (before they signed in) join them too.

Metric definitions

MetricDefinition
SessionsSessions with at least one event in the period (web-vitals measurements alone do not make a session).
VisitorsDistinct visitors over those sessions. An identified user counts once, across devices.
PageviewsPageview events.
EventsInteraction events: custom events, outbound link clicks, clicks, form submissions, input changes and copies.
Views per sessionPageviews divided by the sessions that have a pageview.
Bounce rateSessions with exactly one pageview and no interaction event, out of the sessions that have a pageview.
Visit durationTime from the first to the last event of a session, for sessions with a pageview (average and median).
Time on pageTime from a pageview to the next pageview of the same session, between 0 and 30 minutes; the last page of a session is left out.
Entry and exit pageThe first and the last page viewed in a session.
OnlineVisitors seen in the last five minutes.

A percentage in a breakdown is the row's value out of the period's total for the same metric, not out of the sum of the rows shown.

Session attribution

Each session carries one source, from its own events:

  • Referrer, campaign and affiliate: the first non-empty one in the session.
  • Channel: the first one other than Direct or Internal, if the session has one; otherwise its first.
  • Entry page: its first pageview.

The channel of each request is decided in this order:

  1. Campaign tags and ad click ids (utm_medium, utm_source, gclid, msclkid, fbclid, ...): Paid Search, Paid Social, Display, Email, Affiliate or Paid Other. A social click id such as fbclid without a paid utm_medium means Organic Social: Facebook, for example, adds fbclid to links in unpaid posts too.
  2. The referring site, from PilotFox's lists: Organic Search, Organic Social, Video, AI (assistants such as ChatGPT, Claude or Perplexity), Email (webmail) or Shopping.
  3. Your own site as the referrer: Internal.
  4. Neither a referrer nor campaign tags: Direct.
  5. Anything else: Referral.

Visits from some apps and social sites arrive without a referrer and would count as Direct. Tag the links you share with utm_* parameters (Site settings → Link builder makes them) so those visits are reported under their campaign.

Reports

ReportWhat it is for
DashboardVisitors, sessions, pageviews, bounce rate and duration over time, with breakdowns by page, entry and exit page, referrer, channel, campaign, country, region, city, browser, operating system, device, language and more. Filters combine these dimensions, and a period can be compared with the one before it or the same period a year earlier.
RealtimeThe dashboard's Online count and its Realtime view: visitors active now, with their pages, sources and locations.
Sessions and UsersEach session's pages and events in order; each user's sessions, devices, locations and traits.
EventsEvent names with their counts and properties.
Goals, Funnels, Journeys, RetentionConversions, multi-step funnels, the common paths through your pages, and how many users come back. See Events and identify.
ReplaysRecorded sessions, when session replay is on.
Web vitalsLCP, CLS, INP, FCP and TTFB percentiles, rated against Google's thresholds, when Web vitals is on.
ErrorsJavaScript errors, grouped by error name, message (with numbers, ids, quoted strings and URLs ignored) and the top frame of the stack, when JavaScript errors is on.
BotsWhat the bot filter kept out of your reports and why, with AI crawlers and assistants by operator.
MapVisitors by location.
Revenue, Affiliates, Search ConsoleSee Revenue, Affiliates and Search Console.

The app reads every report from the REST API, so an API key with the right permissions can read them too.

Quickstart

From sign-up to the first tracked visit: create an account, add a site, install the script and verify it.

Tracking overview

How the PilotFox tracking script works, what it records and the global object it defines.

On this page

From a request to a visitor and a sessionUsersMetric definitionsSession attributionReports