Skip to content

Docs attribution: first-touch cookie, tagged console links, signup referrer - #365

Merged
bbnoy merged 2 commits into
mainfrom
binoy/docs-first-touch-attribution
Nov 16, 2026
Merged

bbnoy merged 2 commits into
mainfrom
binoy/docs-first-touch-attribution

Conversation

@bbnoy

@bbnoy bbnoy commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

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

  1. fern/custom.js writes agentmail_attribution_v1 on Domain=agentmail.to; Path=/; Max-Age=2592000; SameSite=Lax; Secure on page load, on agentmail.to hosts only. An existing parseable cookie keeps its first_touch; only last_non_direct_touch is updated, and only when this visit is non-direct (a UTM is present, or the referrer is neither $direct nor an owned host). With no cookie, first_touch is written from the pathname (prefixed with /docs on 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.
  2. scripts/tag_console_links.py adds utm_source=docs&utm_medium=docs&utm_campaign=<page slug> to every Markdown link and JSX href to https://console.agentmail.to, appending to an existing query string and skipping fenced code blocks. --check exits non-zero if any link is untagged. 69 links across 45 files were tagged.
  3. Agent onboarding and quickstart self-signup examples (Python, TypeScript, CLI, cURL) pass referrer set to the page URL, https://docs.agentmail.to/agent-onboarding or https://docs.agentmail.to/quickstart. Those URLs already arrive as referrer values 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.ts in agentmail-web (working tree as of 2026-11-13, including the uncommitted owned-referral change). The console's readAttribution discards a cookie without a top-level expires_at (epoch ms, later than now), so the docs cookie carries it alongside first_touch and last_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 as referring_domain, while a same-host referrer writes nothing.

Consent rule

Check against packages/next-ui/src/lib/consent.ts:

If agentmail_consent_v1 exists and is not 1 or true, write nothing. If it does not exist: write nothing when navigator.globalPrivacyControl is true; write nothing when agentmail_consent_region is absent or is not opt-out; otherwise write.

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.js passes; 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's readAttribution.
  • python3 scripts/tag_console_links.py --check reports 69 tagged, 0 untagged.
  • fern docs dev could not bootstrap its preview bundle on this machine (Fern's own pnpm i esbuild step fails inside ~/.fern), so the rendered page was not checked locally.

🤖 Generated with Claude Code

bbnoy and others added 2 commits November 14, 2026 06:07
…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
bbnoy force-pushed the binoy/docs-first-touch-attribution branch from 6fb3cc1 to 11cfc00 Compare November 13, 2026 22:07
@github-actions

Copy link
Copy Markdown

@bbnoy
bbnoy merged commit 3ec72c8 into main Nov 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants