Custom Tracking Links

Status (2026-10-13): mint, capture, strip, rollup, dashboard and lead conversion attribution are shipped on branch feat/tracking-links (Jira WEB-115). The pipeline phase cannot ship live: it is blocked on the Salesforce sync (WEB-112) and is off by default. Design: docs/superpowers/specs/2026-10-09-tracking-links-design.md.

This page serves two readers. Operators (marketing) want the runbook and how to read the numbers. Engineers want the lifecycle, and the reasoning behind choices that look wrong until you know why. Each rule below is stated with its reason, because the code can only show what it does.

Related pages: the capture side lives in Lead Attribution & Journey, the event pipeline in Content Engagement Telemetry, and the dashboard and route contracts in Lead Attribution & Tracking Links.

Why real URLs with ?mt=, not a /go/ redirect shortener#

A shortener (matters.ai/go/abc) that 301s to the page was the obvious design and was rejected. SEO was the stated priority, and a redirect hop costs on two fronts:

• Link equity. A link that resolves through a redirect passes its value to the destination less cleanly than a direct link, and the shortener URL itself becomes the thing people link to and share.
• Rich previews. LinkedIn, Reddit and X build the preview card by fetching the URL that was pasted. With a real URL they read the destination page's own title, description and image directly. A redirect makes that depend on how each crawler follows it, and on those platforms the preview is what drives click-through.

So the posted URL is the page, e.g. https://matters.ai/blogs/x?utm_source=linkedin&utm_medium=social&utm_campaign=q4&mt=7K2M9QXD4T. The cost is a longer URL, which is why the parameter is two characters (TRACKING_PARAM = "mt", lib/tracking/url.ts) and why mt carries identity: analytics joins on the code, never on the UTM labels, which are editable.

Two consequences that must not be undone:

• Canonicals must ignore the parameters, or the tracked URL competes with the clean one. See Canonical rules.
• The address bar is stripped after capture, so a visitor who copies the URL from their browser re-shares the clean page rather than your tracked link. See Lifecycle step 6.

The code format#

lib/tracking/code.ts. A code is 10 characters of Crockford base32: 0123456789ABCDEFGHJKMNPQRSTVWXYZ, which is the 32-symbol alphabet minus I, L, O and U.

mt_unknown (UNKNOWN_TRACKING_CODE) is deliberately not a valid code: it contains an underscore and is the wrong length, so it fails TRACKING_CODE_PATTERN. Any filter on codes must allow it explicitly, or the "record the mangled paste" behaviour is silently discarded.

Lifecycle#

mint, post, arrive, resolve, record, strip, roll up, display, convert, reconcile. Each step and the file that owns it:

Why the cookie only fills a gap#

The proxy resolves the code server-side and sets mai_mt. The telemetry ingest route reads it and stamps it on the first pageview only when the pageview's own URL carried no code. This covers a visitor whose JavaScript was blocked at landing, or whose browser stripped the query before scripts ran. The URL's own code always wins, because it is the explicit signal for that navigation and the cookie may predate it.

• The cookie is httpOnly, so page script can neither read nor forge it. (The first design had the client read it, which is impossible under httpOnly; the read moved server-side.)
• It stamps the first pageview only. The cookie describes an arrival, and stamping later navigations would turn one visit into several.
• It is deleted only when it was actually consumed. A first batch with no pageview must not clear it, or the attribution is lost.

The proxy path never breaks a page#

resolveArrival never throws. This code runs in proxy.ts on a URL a stranger controls, so the only acceptable failure is degraded attribution. On a lookup error or timeout it keeps the raw, well-formed code rather than writing mt_unknown: an unreachable database is not evidence the code is unknown, and status is settled later at rollup. (Writing the sentinel there would permanently mis-record a visitor on a valid link whenever the database blipped.)

The gate (shouldResolveArrival) admits only a GET document navigation carrying a well-formed mt. It excludes /api/, assets (by an extension allowlist, so /webinars/q3.2026 is still a page), prefetch and RSC requests. Without it every asset request carrying mt would cost a database read. It is not a defence against a client that forges headers: curl with Sec-Fetch-* set passes. Repeats are bounded by MissCache (5,000 hashed codes, 60 s TTL, true LRU). A flood of distinct random codes still costs one findOne each and needs edge protection (WEB-119).

Status semantics#

• Nothing is ever deleted (there is no DELETE route) and a code is never reused. A URL posted in public is permanent: people will keep clicking it for years. Reusing its code would silently merge two campaigns' data. Archiving is how you retire a link.
• Pause is "stop counting", not "break the link". The page still loads and the visit is still stored; it simply is not reported.
• The UI marks status with a non-colour cue plus the word (● active, ‖ paused with a dashed border, ○ archived and dimmed).
• The UI offers Pause/Resume and Archive, and an archived link shows a Restore button (TrackingLinkTable.tsx) that sets it back to active. The API accepts the same change through PATCH with status: "active".

Status is resolved at rollup, not at ingest#

This is the most important design decision to preserve. The capture path stores events raw, with whatever code the URL carried and no status check. Status is applied later, in resolveBucketCode (lib/tracking/rollup.ts):

Why not enforce at ingest? Events are raw facts, and status is a reporting concern. Enforcing it at ingest would destroy the record: a paused link's traffic would never be stored, so you could not later answer "did anyone still click that paused link?". Resolving in the collect route would also add a database read to a hot public path, and rewriting the URL in the proxy would erase what was actually visited. The rollup takes a status Map as an argument so it stays pure and database-free, and one function owns both the "drop" and the "rewrite to unknown" decisions so they cannot drift.

The proxy treats an archived link as mt_unknown, but that only feeds the cookie. In reports, a visit on an archived link whose URL carried the real code is dropped, not shown as mt_unknown, because the rollup sees the real code and its archived status.

renderedUrl is immutable#

renderedUrl records the URL actually posted. The edit endpoint (updateTrackingLinkSchema) omits it, mt and targetPath, and .strip() discards any renderedUrl a caller sends. Editing a campaign name, content, term, placement, notes or tags relabels the link in reports but does not change what was posted.

This is deliberate. The link is already in public; rebuilding renderedUrl would make the stored record disagree with the URL in the wild. So after editing a campaign name, the copy button still yields the old utm_campaign, which is the truth about what was posted. Minting a URL with new UTMs means minting a new link: use Duplicate to channel. Retargeting a code to a different page is likewise not possible, since it would rewrite the meaning of every click already recorded.

Reading the numbers#

Visits are arrivals, not pageviews#

Only the landing pageview carries a code (the later pageviews have a stripped URL), so the rollup treats the two kinds of event differently:

• Engagement (reads, engaged time, bounces) attributes through the session: every event inherits the code of its session's earliest code-bearing event. Without this, scroll-depth and engaged-time beacons arrive codeless and every link would read 0 reads, 0 engaged time and a 100% bounce rate. That was a real defect caught in review: plausible, wrong and actionable.
• visits counts only pageviews carrying their own code. The recorder fires a pageview on every route change, so counting inherited ones would report five visits for a five-page session and make a link's score scale with how much people browse after clicking it.
• A session that spans two codes belongs to the earliest (exact ties go to the smaller code, so the result does not depend on read order). Bot events are skipped so a crawler cannot claim a human's session.
• A bounce is a session whose only event is a pageview. A landing plus an internal navigation is not a bounce. A session with only a click or copy event is not either.

The client-supplied trackingCode on non-pageview events (acceptClientTrackingCode in build-event.ts) is validated but nothing in the client populates it today; session attribution is what actually works. Do not rely on it.

Counter caveats#

• uniqueVisitors is visitor-days, an upper bound. It is summed per day, so the same person returning on two days counts twice. A true cross-day unique would need the raw events, which the list view does not justify reading. The UI says "visitor-days" and never "unique visitors".
• Rates need 20+ visits (MIN_VISITS_FOR_RATE); below that a dash is shown, since a percentage from a handful of visits is noise. A rate above 100% is a counting bug, not a success: it is clamped for display and flagged above INCONSISTENT_RATE_THRESHOLD (1.05) rather than silently accepted.
• Charts end at the latest rolled-up day ("through date"), not at today. The cron folds yesterday only, so today has no row, and drawing it as zero would read as a traffic collapse on every link, every day.
• Video completions are not displayed. The rollup computes them, but the only video_progress producer never emits a depth, so the count is always 0, and "0 completions" claims nobody finished a video. It stays hidden until something emits real progress.
• Medians of daily medians are weighted by each day's visits (weight: row.visits in lib/tracking/performance.ts), so a 500-visit day outweighs a 1-visit day. It is still a median of per-day medians, not a median over every visit, so read engaged time as indicative.

Why there is no "destination vs page" verdict#

A comparison of the link's read rate against the page's overall read rate was built and then removed. The two figures are not like-for-like in two independent ways:

1. Denominators differ. The link rate is distinct readers over arrival-only visits; the page rate is distinct readers over all pageviews, including refreshes and in-site navigation.
2. Numerators differ. Link reads attribute through the session (a reader who opened other pages still credits this link); page reads attribute by path.

The bias is built in, not sampling noise, so a "better/worse than the page" verdict would be wrong with confidence. A "rest of page" baseline is not computable because the daily rows do not hold the link's own pageviews or path-only reads. The page therefore shows both rates side by side with no verdict, plus the link's share of the page's traffic. A confident wrong number is worse than no number: do not reintroduce one without fixing both the numerator and the denominator.

mt_unknown#

Shown in its own Unrecognised codes card and excluded from every campaign, channel and page total. It means a visitor arrived with a well-formed 10-character code that matched no registry row. Causes, in rough order:

1. A posted link was mangled in transit (one character altered, or a platform rewrote the URL; the length is still 10).
2. A code from another environment (a staging or local mint) reached production.
3. A registry lookup failed or timed out and the code has no row at rollup time.
4. Someone is probing with made-up codes.

What to do: open the card, find the date range, and look at the referrers and landing pages in the raw telemetry for that window to see which post it came from. If it is a real post, re-mint the link and replace it. If it is a steady trickle, a mangled link is live somewhere. A spike on one day with no matching post is probing, which is bounded by the miss cache and needs no action.

A truncated code (wrong length) is not well-formed, so it is not recorded as mt_unknown: the visit lands as an ordinary visit with whatever utm_* survived, or as direct. The dashboard card says so as well.

Canonical rules#

A tracked URL and the clean page are the same content at two URLs, so every page must canonicalise to the clean one or the parameters cost ranking signal. Two pre-existing holes were closed while building this module, and tests/seo/canonical.test.ts exists so they do not reopen:

1. No root canonical. The default was commented out, so a page that set none declared none. It is now canonical: "./" in app/root-metadata.ts. It is "./" and not "/": Next resolves "./" against the requested pathname (query string excluded), giving a true per-route self-canonical. A literal "/" resolves to the homepage, which would have declared webinars, datasheets, whitepapers, newsroom, about, careers, tools and demo as duplicates of /. That is actively harmful, where the original bug was merely absent signal.
2. A blanket canonical: "/blogs" in app/blogs/layout.tsx that every descendant inherited (the cause of WEB-94). It was removed. The /blogs listing is a client component and cannot export metadata, so it now lives in client-page.tsx behind a server page.tsx that owns the listing's bare-path canonical. The two 404 patches stay: a missing post must not be indexed.

The test asserts on the real exported metadata, resolved through Next's own URL resolver, not on file text, so it fails for the right reason. Adding a route that sets its own canonical is fine; removing ./ from root metadata is not.

The pipeline phase is gated off#

TRACKING_PIPELINE_SAMPLE_DATA_ENABLED (default off, parsed in packages/lib/src/config/env.ts, read by isPipelineAvailable in lib/services/tracking-pipeline.service.ts).

• Until WEB-112 provides the Salesforce sync, the only store is MockPipelineStore, fed by buildSampleOpportunities: invented opportunities in GBP and INR. The phase cannot ship live.
• With the flag off, loadTrackingPipeline returns { status: "unavailable" } before touching the registry or generating anything; a test asserts getDb is never called. The honest default is "this feature is not available", not "here is some invented money with a caveat".
• The route is always mounted and gated only by org:marketing:view, so before the flag existed a merge would have shown fabricated revenue to every role holder in production. The label alone was not a safe guard because it can fail open.
• When enabled, every panel and money cell is labelled "Sample data — Salesforce sync pending (WEB-112)". The chip shows for every store except salesforce, the response is Zod-validated so a missing store is a load error rather than figures with no provenance, and the marker is repeated per money cell so a cropped screenshot still carries it.
• Mixed-currency links report totals as null, never a coerced zero, and sort by count, not money.
• There is intentionally no NODE_ENV guard: enabling the flag is an unambiguous deliberate act, and a guard would block demoing the panel in staging. Do not set it in production. Going live is a change to resolvePipelineStore only; callers read the PipelineStore interface.

Conversion attribution#

attributionFromJourney (lib/tracking/conversion.ts) is the single payload every lead route writes: first-touch and last-touch codes, sources and campaigns, plus touchCount. Both ends are kept because neither alone is honest for a visitor who found you on Reddit and converted three weeks later from a newsletter.

• It is total. The journey is client JSON, so it accepts null, non-objects and junk, clamps text to 200 characters, and accepts only a code matching TRACKING_CODE_PATTERN or mt_unknown. A conversion must never fail for want of attribution.
• Ten lead routes are wired. A drift-guard test scans for lead-persistence primitives, but it is a tripwire, not a proof: a route using a primitive not on its list, a Server Action, or a route outside the scanned trees can slip past. New lead routes must call attributionFromJourney.
• Repeat submissions do not overwrite first-touch ($setOnInsert for first-touch fields; $set only non-empty last-touch fields). A re-download from a new device has no journey and must not wipe the stored first touch.
• The journey is bounded (lead-journey.ts: size and depth caps) and an oversized one is dropped, not rejected, so the conversion survives.
• Sales export maps two separate canonical fields, firstTrackingCode and lastTrackingCode. The bare trackingCode and mt aliases are deliberately absent: field mapping resolves dot paths on the leaf, so a bare alias would map a last-touch code onto the first-touch field and make every lead look single-touch.
• The overture subscription pool and Salesforce pushes do not carry attribution yet (WEB-112 for the latter); the lead records themselves are correct.

Operator runbook#

Mint. Workspace, Lead Attribution, Tracking Links. Choose the destination from the picker. The mint and bulk routes also verify it server-side (assertMintableDestination, lib/tracking/destination-guard.ts): a path that is not in the destination catalogue is rejected with a 400, so a direct API call cannot mint a link to a 404. The catalogue is the compile-time pages (the sitemap's static routes in lib/seo/static-routes.ts, the platform and key-feature menu pages, and the listing pages in lib/tracking/static-destinations.ts) plus the published content loaders: blog posts, webinars, glossary terms, datasheets, whitepapers, active campaign pages (/c/*), author pages, and the WordPress industry, use-case, key-feature and platform pages. /platform and /key-features are not offered because next.config redirects both to the homepage. Case studies and /tools/* (a "moved to the workspace" notice) are listed as unsupported in the picker. A path with no owning source can never produce the retryable 502. If the content source that would hold the path is down, the mint fails closed with a retryable 502 (a code is permanent, a retry is cheap), and an outage in an unrelated source does not block it. a channel preset (curated, so Reddit and reddit never become two channels), a campaign and the exact placement. Use Bulk for several channels; a partial failure returns 207 with the codes already issued and the channels still owed, so retry only those (a blind full retry would create duplicate links, since codes are permanent).

Retire a campaign. Set each link to Archive (or Pause if it may return), early in the day (see the warning below: a mid-day change drops that whole day). Do not look for Delete: it does not exist. The posted URLs keep working and the visits are still stored; they stop being reported from the next daily fold. History already rolled stays.

Correct a mislabelled link.

• Wrong campaign / content / term / placement / notes / tags: Edit labels. Reports regroup. The copy button still shows the originally posted URL, which is correct.
• Wrong destination or channel, or you need different UTMs in the URL: you cannot edit these. Duplicate to channel (or mint anew), re-post the new URL, then Archive the wrong one.

A link's numbers look wrong. Work down this list:

1. Zero or flat at the end of the chart. Expected: the chart ends at "through date", and yesterday is not folded until 01:20 UTC. Wait before concluding anything.
2. Status. A paused or archived link counts nothing. Was it paused when the day was folded? (See the status callout: it is the fold time that matters.)
3. Fewer visits than clicks you expect. Visits are arrivals through the code. Link previews and bots are not counted. A change to the code in transit appears under Unrecognised codes.
4. Everything appears as mt_unknown. If many real links do, suspect a registry or lookup problem rather than the links: the rollup folds a code with no row into unknown, and the cron throws rather than misreport when it cannot read statuses. Check the cron logs.
5. Unique visitors too high. It is visitor-days; one person over a week counts up to seven times.
6. Rates show a dash. Under 20 visits.
7. Edits not showing. A status edit evicts the resolver cache, but other server instances serve the old value until their 60 s entry expires.
8. Cron aborted. A day with more than the 200,000-event cap fails loudly and writes nothing; it does not publish a partial day.

Known gaps#

• No per-link conversion count or rate. The design promised both on the dashboard. They were never built, and the conversions field on TrackingLink (always 0, never updated) and its CSV column were removed rather than ship a number that was wrong. Leads do carry first-touch and last-touch codes (lib/tracking/conversion.ts), but they live in several collections, so a count needs a cross-collection aggregation that does not exist yet. Until it does, conversions per link can only be read from the lead records themselves.
• The registry list and the dashboard cap at 500 links (TRACKING_LIST_MAX_LIMIT). Both now show a banner when the registry holds more; the oldest links are the ones left out, including from the CSV export.
• Theme tokens (WEB-121). Several variants fail contrast on ws-btn-primary (accent on accent) and ws-chip--yellow. This module therefore signals state with non-colour cues: status glyphs with border and opacity, selected range/group toggles as the ink pair with a border and underline, and the sample-data chip as glyph, dashed border and words. Do not move any of these back onto an accent or yellow token.
• Rate limits are not abuse protection. The shared limiter trusts the first x-forwarded-for value (WEB-119), so treat it as accident protection only. Authorization (checkRole) is the real gate on every registry route.
• getAllCategories returns only WordPress's default 10 categories (WEB-120), so special categories ranked past 10 are not seen by the blog picker. It matches live site behaviour today and will follow when that is fixed.
• cachedFetch's memory layer is unbounded (WEB-118); hence the throw-on-miss above.
• Raw events are retained for 90 days. After that a day can no longer be re-rolled.

Key files#