Review draft · 28 Oct 2026

Unsent draft for Som to send to Austin and Kevin. No Hypertune figures. Live site checked 28 October 2026.

E7-1: AI tracking spec for Kevin

Task: E7-1. Due 4 Nov 2026. Status: draft. Som sends it to Austin and Kevin.

Prepared 28 Oct 2026. No Hypertune figures in this spec. All tables are empty layouts.

Why

We want to know if AEO earns its time. To know that, we must count paying customers who came from AI answers. This spec says what to track, where to store it and how to count it once.

What the live site already loads

A GET of https://hypertune.gg/ on 28 Oct 2026 showed:

Google Analytics 4 (G-MHWGLY4TPD) and Google Ads (AW-16466588746) via gtag.js.
Microsoft Clarity, Meta Pixel, X (Twitter) pixel and Reddit Pixel.
Cloudflare Web Analytics beacon. Responses come through Cloudflare (Server: cloudflare, CF-RAY), with Railway headers behind it.
Next.js, with Clerk auth headers. Page text mentions "Add card via Stripe".
An existing referral tracker. It keeps the real entry referrer in sessionStorage (ht_entry_referrer) because the consent banner reloads the page on Accept. It hands that to GA4 as page_referrer.
An affiliate cookie ht_am_id, and the hosts affiliate.hypertune.gg and loggregator.hypertune.gg.
Google Consent Mode with a region list (EU, EEA, UK, Switzerland) and wait_for_update.

This spec builds on the existing ht_entry_referrer tracker. It does not assume which tool is the source of truth. See the questions at the end.

1. AI visits by engine and landing page

Detect on the first page view of a session. Check utm_source first, then the entry referrer hostname. Use ht_entry_referrer, not document.referrer, after a consent reload.

Engine	Referrer hostnames	utm_source values	Notes
ChatGPT	`chatgpt.com`, `chat.openai.com`	`chatgpt.com`	OpenAI says ChatGPT adds `utm_source=chatgpt.com` to referral links. In October 2026 some links lost the tag; reports say a fix began on 15 Oct. App links may send no referrer.
Perplexity	`perplexity.ai`, `www.perplexity.ai`	`perplexity`, `perplexity.ai`	Usually passes a referrer.
Gemini	`gemini.google.com`, `bard.google.com` (old)	`gemini`	Separate from Google Search.
Copilot / Bing chat	`copilot.microsoft.com`, `copilot.com`, `copilot.cloud.microsoft`, `edgeservices.bing.com`	`copilot`	Never match plain `bing.com`. That is Bing organic.
Claude	`claude.ai`	`claude`, `claude.ai`	Often sends no referrer.
Other AI	`chat.deepseek.com`, `grok.com`, `meta.ai`, `chat.mistral.ai`, `you.com`, `poe.com`	same names	One bucket.
Google AI Overviews / AI Mode	`google.com`	none	Cannot be split. These clicks arrive as normal Google organic. Google reports them inside the Search Console "Web" search type. We count them only through the self-reported answer.

Rules:

Match the hostname exactly or as a subdomain. Keep the list in one config file. Review it every quarter.
Store the landing page as the path only (for example /guides/cs2). Strip the query string.
Visits with no referrer and no tag are Direct. Some AI traffic will hide there. We accept that undercount.
If the medium is paid (cpc, paid), do not count it as AI.

AI crawler hits (separate count)

Count bot hits from Cloudflare or origin server logs by user agent. Never add them to human visits. Bots do not run GA4, so they will not appear there anyway.

Bot token	Owner	What it does
`GPTBot`	OpenAI	Crawls for model training.
`OAI-SearchBot`	OpenAI	Crawls for ChatGPT search results.
`ChatGPT-User`	OpenAI	Fetches a page when a user asks.
`PerplexityBot`	Perplexity	Crawls for Perplexity search results.
`Perplexity-User`	Perplexity	Fetches a page when a user asks.
`ClaudeBot`	Anthropic	Crawls for model training.
`Claude-SearchBot`	Anthropic	Crawls for Claude search quality.
`Claude-User`	Anthropic	Fetches a page when a user asks.
`bingbot`	Microsoft	Crawls for Bing. Copilot answers draw on Bing.
`Google-Extended`	Google	Not countable. It is a robots.txt control token only, with no user agent of its own. Googlebot hits cannot be split into AI and search.

Check IPs against the published lists (https://openai.com/gptbot.json, https://www.perplexity.com/perplexitybot.json) to drop fakes. Group hits as training, search and user fetch.

2. Paying customers three ways

A paying customer is an account with a first successful paid subscription charge. Kevin to confirm how trials and refunds count.

Last touch. The AI engine on the session where the person signs up or pays. Read from sessionStorage ht_ai_lt.
First touch. The AI engine on the person's first AI visit. Write a first-party cookie ht_ai_ft once, and never overwrite it. Pass it to signup and checkout. Suggested lifetime: 90 days.
Self-reported. Ask "How did you hear about us?" once, at signup or checkout. Options: ChatGPT; Perplexity; Google AI answer (AI Overview or AI Mode); Other AI (Claude, Gemini, Copilot and others); Google search (normal results); YouTube or a streamer; Reddit or Discord; A friend; Other. Show the options in a fixed order. The question is optional.

One deduplicated count

A customer counts once if any of the three says AI.
Credit one engine with this precedence: first touch, then last touch, then self-reported.
If only the self-report says "Google AI answer", credit "Google AI (self-reported)".
If tracked and self-reported engines disagree, keep the tracked engine. Count the disagreements in a separate column.
Deduplicate on the internal customer ID in Hypertune's own database. Never send that ID to analytics.
Affiliate credit (ht_am_id) is unchanged. A customer can be both affiliate and AI.

3. Fields, storage and events

Field	Example	Stored in
`ai_engine`	`chatgpt`	`ht_ai_lt` (sessionStorage) and `ht_ai_ft` (cookie)
`ai_method`	`utm` or `referrer`	same
`ai_landing_page`	`/guides/cs2`	same
`ai_first_date`	`2026-11-02`	`ht_ai_ft` only (date, no time)
`hdyhau`	`perplexity`	customer record
`ai_engine_ft`, `ai_engine_lt`, `ai_landing_page_ft`	copied at signup	customer record and checkout metadata

Events (names work in GA4 or any tool):

ai_visit: once per session when an engine is found. Params: ai_engine, ai_method, ai_landing_page.
sign_up: params ai_engine_ft, ai_engine_lt.
hdyhau_answered: param hdyhau.
purchase: params ai_engine_ft, ai_engine_lt, hdyhau. Fire on the first paid charge only, or add is_first_payment.
Bot hits are not events. They are a weekly log query.

Weekly table layout

Week	Engine	Landing page	AI visits	Signups	Paying (last touch)	Paying (first touch)	Paying (self-reported)	Paying (deduplicated)
2026-W45	ChatGPT	/guides/cs2	-	-	-	-	-	-
2026-W45	Perplexity	/	-	-	-	-	-	-

Self-reported rows have no landing page; show "(none)". A second table holds bots: Week, Bot, Group, Page, Hits.

Privacy

No personal data in analytics. No email, name, customer ID or IP in event params.
Only the engine name, method, page path and date go in the cookie.
Follow the existing consent banner. Where consent is required, do not write ht_ai_ft or fire ai_visit until analytics consent is granted. Then read ht_entry_referrer.
Add ht_ai_ft and ht_ai_lt to the /cookies page.

4. QA checklist for Kevin

Open https://hypertune.gg/?utm_source=chatgpt.com in a private window. ai_visit fires with chatgpt and utm.
Click a real hypertune.gg link in a Perplexity answer. ai_visit fires with perplexity and referrer.
Land from an AI link as a UK or EU visitor, then accept the banner. After the reload, the engine is still kept.
Same visit, but decline. No ht_ai_ft cookie, no ai_visit.
Land from ChatGPT, close, return direct the next day, sign up. First touch is chatgpt. Last touch is empty.
A normal Google search click and a plain bing.com click are not AI.
Sign up and answer the question. The answer is on the customer record.
Make a test purchase in checkout test mode. The metadata carries the first and last touch fields.
Make one test customer AI on all three. They count once, credited to first touch.
Check event params in the analytics debug view. No email or customer ID appears.
Run the bot log query. Bot hits are absent from the human visits table.

Sources (checked 28 Oct 2026)

OpenAI, Publishers and Developers FAQ (utm_source=chatgpt.com): https://help.openai.com/en/articles/12627856-publishers-and-developers-faq
OpenAI crawlers (GPTBot, OAI-SearchBot, ChatGPT-User): https://developers.openai.com/api/docs/bots
Perplexity crawlers (PerplexityBot, Perplexity-User): https://docs.perplexity.ai/docs/resources/perplexity-crawlers
Anthropic crawlers (ClaudeBot, Claude-SearchBot, Claude-User): https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler
Google-Extended has no separate user agent: https://developers.google.com/crawling/docs/crawlers-fetchers/google-common-crawlers
AI Overviews and AI Mode counted in Search Console "Web": https://developers.google.com/search/docs/appearance/ai-features
ChatGPT UTM loss in October 2026: https://searchengineland.com/chatgpt-appears-to-drop-utm-tracking-making-ai-referral-traffic-harder-to-measure-496552 and https://www.searchenginejournal.com/chatgpt-traffic-drop-appears-to-be-a-tracking-problem/593157/
Referrer hostnames (third-party lists): https://wandered.io/ai-assistants and https://www.terminusapp.com/blog/tracking-ai-referral-traffic/
Bing crawlers page (could not be read by script; Kevin to confirm): https://www.bing.com/webmasters/help/which-crawlers-does-bing-use-8c184ec0

Questions for Kevin and Austin

Which tool is the source of truth for visits and conversions: GA4, Cloudflare Web Analytics, Clarity, or your own loggregator.hypertune.gg?
Which checkout provider takes payment? The page mentions Stripe. Can we attach metadata to the checkout or subscription?
Where does signup happen: on the website (Clerk) or inside the Windows app? If in the app, how can first touch from the website reach the app account?
What counts as a paying customer: first charge after a trial? Do refunds remove them?
Can we get Cloudflare logs or origin (Railway) logs with user agents? Which Cloudflare plan is it?
Is a 90-day first-touch cookie fine? Who updates the /cookies page?
Austin: do you approve the "How did you hear about us?" wording and options, and should it sit at signup or checkout?
Does the GA4 property already show an "AI Assistant" channel? If yes, we still add our own channel group. We could not find a Google list of the sources it covers, and ours names Perplexity and Claude.