Documentation
Site search, downloads, 404 pages and visitor privacy
Turn on Friction and site search in Settings → General → Tracking add-ons and your main tracking tag loads the behavior add-on by itself. If you serve the tracker through a first-party proxy, forward all of /js/*, not only /js/script.js, so the tracker can load its add-ons from the same place.
Or add the script by hand after your main analytics tag. Use your tracking host if you proxy the scripts:
<script defer src="https://t.analyticfast.com/js/script.js" data-website-id="YOUR_SITE_ID"></script>
<script defer src="https://t.analyticfast.com/js/behavior.js"></script>
The core tracker is unchanged. The add-on shares its consent, cookieless and opt-out handling through window.analyticfast. It never reads input values. A page sends at most 20 behavior signals in total, including friction signals; extra signals are dropped quietly. [data-af-ignore] excludes download clicks and friction tracking beneath that element.
Internal site search
Searches come from page URL parameters, in this priority order: q, s, search, query, keyword, k. The first non-empty term is trimmed, lowercased, whitespace-collapsed, redacted for email-like strings and digit runs of five or more digits, then clipped to 100 characters. Search input fields are never read.
The standard tracker deliberately removes these query parameters from its pageview payload (u); it only retains attribution parameters. For that reason, the add-on reports an af_site_search diagnostic containing the URL term at document load. Custom clients that send full pageview URLs get search extraction at ingest instead. When a full URL contains a search term, its diagnostic is ignored to avoid double counting.
The report shows the top 50 terms, total searches (including the tail), and searches divided by pageviews. Its denominator is a new daily pageview counter, starting when this feature is installed; older traffic is not backfilled. These are observed search-result page loads, not unique searchers or submitted forms. Normal document loads are automatic; SPAs should report the reserved diagnostic once when they render new search results:
window.analyticfast('track', 'af_site_search', { term: 'running shoes' });
Do not report it again if your custom pageview client already sends the full URL. Next-page destinations are intentionally omitted: deriving them would require scanning raw journeys.
File downloads
One diagnostic is sent for each observed click on a link with a download attribute or a pathname ending in pdf, zip, dmg, exe, pkg, msi, csv, xlsx, xls, docx, doc, pptx, mp3, mp4, mov, epub, apk, gz, rar, 7z, iso, txt, or json (case-insensitive).
Only HTTP(S) links qualify. Credentials, query strings and fragments are removed before sending the file URL. The server also redacts emails and long digit runs in the stored pathname. These counts measure clicks, not successful transfers. Downloading a large file or a failed transfer does not change the count.
Mark 404 pages explicitly
Put either marker in your not-found template:
<meta name="af-404" content="true">
<!-- Or mark an element: -->
<main data-af-404>We couldn't find this page.</main>
The add-on also recognizes titles containing the standalone number 404, page not found, or not found, case-insensitively. Markers are more reliable, especially on translated sites. The diagnostic runs once at DOM readiness per document; a title match is a heuristic, not confirmation of an HTTP 404 response. For client-side not-found routes, send the signal once after rendering:
window.analyticfast('track', 'af_not_found', { referrer: 'search.example.com' });
The server uses the already validated page URL's pathname and stores only the referring hostname, never its path/query, credentials, or an address literal. Download URLs using address literals are dropped. Page paths are decoded and redacted before storage.
Reports, limits and MCP
GET /api/sites/:siteId/site-searchGET /api/sites/:siteId/downloadsGET /api/sites/:siteId/not-found- MCP tools:
site_search,downloads,not_foundwithsite_id,period, and optional customfrom/todates.
Browser reports require a signed-in member and dashboard entitlement. MCP requires an analytics:read token bound to the correct site/workspace. Viewer reads are allowed; other tenants are never accessible. Reports are whole-site anonymous counters, so session filters do not apply. Dates are inclusive UTC days, capped to the final 31 days of the requested range; the response discloses the effective dates. Edge caches can delay a newly collected diagnostic by up to 60 seconds.
Each aggregate stores at most 200 distinct keys per site/day plus (other). For 404s, a key is the path/referrer pair. Existing keys continue counting after the cap; unseen ones fold into (other). Reports include overflow counts, return the top 50 rows, and never scan raw events. No visitor/session IDs, IP addresses, or form values are attached to these counters. Retention follows workspace plans; aggregate tables participate in account export and site-deletion cascades.
Find and erase a visitor
Look up a visitor with GET /api/sites/:siteId/visitor-lookup?search=VISITOR_ID_OR_EXACT_EMAIL. IDs are exact; identified emails are case-insensitive. ID lookup is a point read. Email lookup scans at most 200 identities per request; if next is present, pass it as after with the same search to continue. This searches historical identities, including visitors without recent activity. The dashboard lookup panel follows those pages automatically. Existing visitor profiles and the MCP visitor_journey tool provide journeys; visitors_search also accepts exact IDs/emails and returns next for bounded email lookup (pass after in the next call). Other searches retain the existing recent-visitor substring behavior.
Workspace owners and admins can choose Delete this visitor's data in the visitor modal and confirm. Viewers cannot delete. This is restricted to a browser session and uses the same Origin/Fetch-Metadata CSRF protection as other cookie mutations. It is available even if a plan has expired.
DELETE /api/sites/:siteId/visitors/:visitorId erases one bounded page at a time. A 202 response contains a signed continue token; repeat DELETE with ?continue=TOKEN until the response is 200 with done:true. The modal follows continuations automatically. Tokens expire after one hour and cannot be transferred to another site or visitor. If interrupted or expired, restart DELETE without a token; it safely revisits remaining data. Do not consider a 202 a completed erasure.
Erasure removes events, sessions, visitor identity, friction signals, checkout clicks, return-page payment claims, provider attribution hints and pending payment payloads. It handles rows linked only through a visitor's sessions, including first-touch payment links. Payments and refunds keep amounts, currencies, transaction/provider identity and subscription records needed for reconciliation, but lose visitor/session links, matched-by status, customer ID, email and name. The financial ledger is retained; anonymous aggregate counters are retained because they cannot be linked back to this visitor. Global billing checkout session IDs are provider sessions, not site visitor sessions.
The audit log contains only an action, changed-row count and completion flag. Collection remains live; deletion removes the observed records and is not a permanent opt-out or a blacklist against future visits/provider deliveries. Disable collection or coordinate consent/checkout systems if a visitor also requests future tracking to stop.
D1 cost
A diagnostic writes one aggregate counter (no raw event/session/visitor rows and no metering). Its atomic admission check reads at most 200 existing daily keys plus indexed point probes; 404 admission checks can evaluate that bounded count twice. A normal pageview adds one denominator UPSERT, plus one search UPSERT only for full-URL clients with a term. Existing ingestion/auth/rate-limit costs still apply. Initial inserts also maintain the new primary-key index; updates touch the counter row only.
A cold downloads/404 report scans at most 31 × 201 = 6,231 small aggregate rows once, using (site_id,day,...). Site search adds at most 31 denominator rows. Normal access/entitlement checks and cache freshness point reads are additional. Warm report cache hits do not repeat aggregate scans.
Each visitor-erasure request scans at most 100 candidates from one indexed site table, plus at most three point probes per candidate for session linkage, and deletes/updates at most 100 records. It runs at most three storage statements (including the rare 100th match split to stay under 100 bound parameters); session cleanup uses at most two. No invocation drains a whole tenant. Deletion traverses historical rows across several requests, so large sites still consume proportional daily D1 reads and writes. The 100k write/day and 5M read/day account allowances remain shared with all other traffic; these bounds do not create extra quota.