Repository navigation
Docs attribution: first-touch cookie, tagged console links, signup referrer - #365
Merged
Merged
Conversation
…ferrer custom.js writes agentmail_attribution_v1 on Domain=agentmail.to so a visitor who reaches the console from the docs carries a source. Every console link in the docs now carries utm_source=docs, utm_medium=docs and utm_campaign=<page slug>, applied by scripts/tag_console_links.py so it can be re-run. The self-signup examples on the agent onboarding and quickstart pages pass a fixed referrer naming the page. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Without an explicit consent answer, the first-touch writer now captures only a visitor the landing middleware has placed in an opt-out region. A missing region cookie waits for the banner, as the landing site does. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
bbnoy
force-pushed
the
binoy/docs-first-touch-attribution
branch
from
November 13, 2026 22:07
6fb3cc1 to
11cfc00
Compare
tvmehta-21
approved these changes
Nov 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs attribution: first-touch cookie, tagged console links, signup referrer
The docs wrote nothing a visitor carried into the console, so anyone who came from search to the docs and then signed up was recorded with no source. This PR closes that gap with one cookie and tagged links. No analytics SDK, no third-party calls.
What changed
fern/custom.jswritesagentmail_attribution_v1onDomain=agentmail.to; Path=/; Max-Age=2592000; SameSite=Lax; Secureon page load, on agentmail.to hosts only. An existing parseable cookie keeps itsfirst_touch; onlylast_non_direct_touchis updated, and only when this visit is non-direct (a UTM is present, or the referrer is neither$directnor an owned host). With no cookie,first_touchis written from the pathname (prefixed with/docson agentmail.to and www.agentmail.to when the path lacks it), the lowercase referrer hostname or$direct, and the UTM params present. Everything is in a try/catch.scripts/tag_console_links.pyaddsutm_source=docs&utm_medium=docs&utm_campaign=<page slug>to every Markdown link and JSX href tohttps://console.agentmail.to, appending to an existing query string and skipping fenced code blocks.--checkexits non-zero if any link is untagged. 69 links across 45 files were tagged.referrerset to the page URL,https://docs.agentmail.to/agent-onboardingorhttps://docs.agentmail.to/quickstart. Those URLs already arrive asreferrervalues from agents that copy the page address, so the fixed value lands in the same bucket.Cookie shape
Taken from
packages/next-ui/src/lib/attribution.tsin agentmail-web (working tree as of 2026-11-13, including the uncommitted owned-referral change). The console'sreadAttributiondiscards a cookie without a top-levelexpires_at(epoch ms, later than now), so the docs cookie carries it alongsidefirst_touchandlast_non_direct_touch. The writer also mirrors the source's rule that a first visit referred by another owned host (the landing site) is kept as a direct-class touch with its origin asreferring_domain, while a same-host referrer writes nothing.Consent rule
Check against
packages/next-ui/src/lib/consent.ts:This matches the landing site: an explicit answer wins, a Global Privacy Control signal is a refusal, and without an answer only a visitor the middleware has placed in an opt-out region is captured. A visitor with no region cookie is treated as opt-in and waits for the banner, as the landing site does.
Verification
fern check: 0 errors.node --check fern/custom.jspasses; the writer was exercised in Node across 14 scenarios (search referral, direct, UTM on agentmail.to/docs, owned-host referral, same-host reload, consent granted/denied, GPC, no region cookie, opt-in and opt-out regions, localhost, revisits with an existing cookie) and every cookie it emitted was parsed by the console'sreadAttribution.python3 scripts/tag_console_links.py --checkreports 69 tagged, 0 untagged.fern docs devcould not bootstrap its preview bundle on this machine (Fern's ownpnpm i esbuildstep fails inside~/.fern), so the rendered page was not checked locally.🤖 Generated with Claude Code