Repository navigation
feat(docs): download links carry the docs visitor's PostHog id - #6468
Conversation
hyperframes.dev counts each Studio download in PostHog, but it cannot read the docs' posthog cookie (another domain), so a download clicked here lands under an id with none of this visit's pageviews. A docs script now adds the id as ph_id when a download link is clicked, and puts the link back afterwards so a copied link never carries it. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
jerrai-bot-heygen
left a comment
jerrai-bot-heygen
left a comment
There was a problem hiding this comment.
Please wire the script into the actual Mintlify page load and verify a normal docs click, then restrict the ID-bearing URL to the intended HTTPS host and demonstrate that consent/opt-out suppresses transfer. The PR currently adds a standalone file without a loader; its manual test injected that file, so it does not validate the shipped path. — Jerrai
…with consent The id now goes only to https://hyperframes.dev/studio/download, the one address the docs link to, never another subdomain or plain http. It is not forwarded when PostHog is not running on the page, when the visitor opted out of PostHog capture, or when the browser sends Do Not Track or Global Privacy Control. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
jerrai-bot-heygen
left a comment
jerrai-bot-heygen
left a comment
There was a problem hiding this comment.
Re-reviewed at 83ecb8f. My earlier loader finding was incorrect: Mintlify documents that .js files in the content directory load site-wide, and the author verified this script in an unmodified PR preview. The updated source restricts ID transfer to the exact HTTPS download endpoint and checks the PostHog opt-out state in browser storage, GPC, and DNT. Hosted docs validation and Mintlify deployment succeeded. I did not independently complete a browser-to-PostHog event or production logging/retention check; the author’s preview click covers the DOM/URL behavior. No code blocker remains. — Jerrai
What
Adds
docs/download-attribution.js. Mintlify loads it on every page. When someone clicks a link tohyperframes.dev/studio/download, the script addsph_id=<the docs' PostHog distinct_id>to it. The id comes from the docs' own posthog cookie. Afterwards the script restores the link, so a copied link never carries the id.Why
The docs and hyperframes.dev send to the same PostHog project (356858). They are different domains, though, so the download route can't read the docs' cookie. A download clicked in the docs therefore lands under an id with none of that visit's pageviews. Since 2026-10-25 12:00 UTC, 977 downloads came from
src=docs-*links, and only 2.8% share a distinct_id with any pageview.Related work
Refs heygen-com/hyperframes-internal#6057. That PR makes the route read
ph_id. Until it ships, the route ignores the extra parameter.How
clickandauxclicklisteners ondocument, so middle-clicks and Mintlify's client-side navigation are covered without per-link wiring. Same approach astemplate-gallery.js.window.posthog, because Mintlify bundles posthog-js and does not expose it..jsfile indocs/on every page (https://www.mintlify.com/docs/customize/custom-scripts#custom-javascript), so the file needs no other wiring.https://hyperframes.dev/studio/download, exactly. It is skipped when PostHog isn't loaded on the page, when the visitor opted out of posthog-js capture (__ph_opt_in_out_<token>), or when the browser sends Global Privacy Control or Do Not Track.Test plan
ph_idmatching the page's own posthog-js id, and eachhrefwas restored afterwards. Other hosts,http:, opt-out (localStorage or cookie), GPC, DNT and PostHog not loaded all left the link unchanged. Earlier, I also injected the script into the livehyperframes.heygen.com/quickstartin headless Chrome and clicked the navbar, sidebar and quickstart download links. Each one followed...?src=docs-navbar&ph_id=01a1797f-...(ordocs-quickstart), and itshrefwas back to the original afterwards. A GitHub link was left alone. The id matcheddistinct_idin the page's posthog-js localStorage.oxlint docs/download-attribution.jsreports 0 findings.docs/is excluded from oxfmt.Not exercised: a real click through to a PostHog event. Headless Chrome is dropped as a bot by posthog-js.
🤖 Generated with Claude Code
— Rames