UTM Attribution skill for Codex

Tracking is done well when every external link a team controls is tagged from one lowercase convention, internal links carry no UTMs, GA4 sorts the traffic into the right default channel, and attribution answers state which model they use and what it cannot see.

Inspect first

1. Read AGENTS.md, then look for existing conventions and link builders: rg -n "utm_(source|medium|campaign)" -g '!node_modules' | head -50.
2. Pull the current reality from analytics: GA4 Traffic acquisition report by “Session source / medium” and “Session campaign” for the last 90 days. List variant spellings (Facebook, facebook.com, fb) and the share of Unassigned traffic.
3. Find where links come from: ad platforms, ESP, social scheduler, partner programs, QR codes, sales email signatures. Each is a source of inconsistency.

The convention

Parameter	Meaning	Rule	Examples
utm_source	Who sent the traffic (site, platform, publication)	Lowercase platform or publisher name, no TLD	google, linkedin, newsletter, partner-acme
utm_medium	Marketing channel type	Fixed allowed list only (below)	cpc, paid_social, email
utm_campaign	The initiative	<yyyy>-<qN or mm>-<slug> or a stable slug	2026-q4-launch, spring-sale
utm_content	Which creative or link within the campaign	Variant identifier	video-a, header-cta
utm_term	Paid keyword or audience	Usually filled by dynamic params	{keyword}
utm_id	Campaign ID for cost data import	Platform or internal ID	cmp_10443

Allowed utm_medium values, chosen to land in GA4 default channel groups:

utm_medium	GA4 default channel (with a matching source)
cpc	Paid Search (source is a search engine) or Paid Social (source is a social site)
paid_social	Paid Social (any value starting with paid counts as paid)
display	Display
email	Email
social	Organic Social
affiliate	Affiliates
referral	Referral
sms	SMS
audio, video	Audio / Paid or Organic Video depending on source

Rules:

• Lowercase everything, hyphens inside values, no spaces. GA4 values are case-sensitive in reports: Email and email become two rows.
• Never put UTMs on internal links (nav, in-app banners, links between your own subdomains). They overwrite the real source for the session. Use an event parameter such as link_location instead.
• UTMs go in the query string before any #fragment; hash-router apps must still put them before #.
• Keep a source of truth: a shared sheet or a utm-conventions.md plus the link builder; update both together.

Building links

Prefer a generator over hand-typing. Minimal builder:

export function tag(url: string, p: { source: string; medium: string; campaign: string; content?: string; term?: string }) {
  const u = new URL(url);
  const clean = (s: string) => s.trim().toLowerCase().replace(/[\s_]+/g, "-");
  u.searchParams.set("utm_source", clean(p.source));
  u.searchParams.set("utm_medium", p.medium);          // from the allowed list, unmodified
  u.searchParams.set("utm_campaign", clean(p.campaign));
  if (p.content) u.searchParams.set("utm_content", clean(p.content));
  if (p.term) u.searchParams.set("utm_term", p.term);
  return u.toString();
}

Dynamic parameters in ad platforms (set once at account or campaign level):

Platform	Where	Example
Google Ads	Auto-tagging (gclid) on; optional final URL suffix	utm_source=google&utm_medium=cpc&utm_campaign={_campaign}&utm_term={keyword}&utm_id={campaignid} with a custom {_campaign} parameter
Microsoft Ads	Auto-tagging setting can append UTMs; msclkid	Check the account setting before adding manual UTMs to avoid duplicates
Meta	Ad level “URL parameters”	utm_source=facebook&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}}&utm_term={{adset.name}}

With Google Ads auto-tagging and GA4 linked, GA4 attributes Google Ads clicks from gclid; keep UTMs consistent anyway for other tools.

Linting links in bulk

scripts/utm_lint.py (standard library, offline) checks a list or CSV of URLs for missing required parameters, uppercase or spaces, mediums outside the allowed list, UTMs after #, duplicated parameters, UTMs on internal domains, and campaigns spelled several ways.

python3 scripts/utm_lint.py links.txt
python3 scripts/utm_lint.py campaign-links.csv --column url --internal example.com,app.example.com
python3 scripts/utm_lint.py links.txt --mediums cpc,paid_social,email,social,affiliate,referral

Exit code 1 means problems; fix and rerun until clean before links go into ads or emails.

Fixing messy historical data

• Do not rewrite raw data. Create a GA4 custom channel group that normalises variants (e.g. source matches regex ^(facebook|fb|facebook\.com|m\.facebook\.com)$). Custom channel groups apply retroactively in reports.
• In the warehouse, build a mapping table (raw_source, raw_medium -> source, medium, channel) and join it in a view.
• For “(not set)” and Unassigned: check for UTMs on redirects that strip query strings, links in apps that open without a referrer, consent mode denying analytics storage, and mediums outside the allowed list.

Attribution analysis

Question	Model / source
Which channel introduces new users?	First touch: GA4 “First user default channel group”, or first session per user
Which channel closes?	Last non-direct touch: GA4 session-scoped reports
Credit across the journey for paid optimisation	GA4 data-driven attribution in Advertising reports (the default model)
Does a channel cause conversions at all?	Incrementality: geo holdouts, conversion lift studies, or pausing a channel
B2B with long cycles	Self-reported attribution (“How did you hear about us?”) alongside clicks

GA4 offers data-driven and last-click models (first click, linear, time decay and position-based were removed in 2023). For other models, use the warehouse.

Warehouse-agnostic example over a touches table (one row per tagged session per user) and a conversions table:

WITH paths AS (
  SELECT c.user_id, c.converted_at, t.channel, t.touched_at,
         ROW_NUMBER() OVER (PARTITION BY c.user_id, c.converted_at ORDER BY t.touched_at)      AS n_first,
         ROW_NUMBER() OVER (PARTITION BY c.user_id, c.converted_at ORDER BY t.touched_at DESC) AS n_last,
         COUNT(*)     OVER (PARTITION BY c.user_id, c.converted_at)                            AS n_touches
  FROM conversions c
  JOIN touches t
    ON t.user_id = c.user_id
   AND t.touched_at <= c.converted_at
   AND t.touched_at >= c.converted_at - INTERVAL '30' DAY       -- lookback window
)
SELECT channel,
       SUM(CASE WHEN n_first = 1 THEN 1 ELSE 0 END) AS first_touch,
       SUM(CASE WHEN n_last  = 1 THEN 1 ELSE 0 END) AS last_touch,
       ROUND(SUM(1.0 / n_touches), 1)               AS linear
FROM paths
GROUP BY channel
ORDER BY last_touch DESC;

Adjust interval syntax for the engine (BigQuery: TIMESTAMP_SUB(c.converted_at, INTERVAL 30 DAY)).

Interpret honestly:

• Click-based attribution cannot see dark social, podcasts, word of mouth, or view-through impressions; brand search often gets credit that belongs to them.
• Platforms (Meta, Google Ads) report their own attributed conversions with their own windows; totals across platforms exceed actual conversions. Do not sum them.
• Consent banners and ad blockers remove a share of users entirely; state the coverage.

Gotchas

• Link shorteners or redirects dropping the query string. Test the final landing URL.
• Social schedulers appending their own UTMs on top of yours; check one published link.
• Partner links with utm_source=partner for every partner; use a per-partner value.
• Email clients’ click tracking wraps links; confirm UTMs survive the redirect.
• Changing the convention mid-quarter without a mapping breaks trend reports.

Verification

• Lint script exits 0 on every link list before launch.
• Click one live link per channel and confirm GA4 DebugView/Realtime shows the expected source, medium and campaign, and the right default channel group.
• Unassigned share in GA4 drops after the fix; record before/after.

Output template

## UTM convention v<N> (owner: <team>)
| Parameter | Rule | Allowed values / pattern |
**Platform settings:** Google Ads suffix, Meta URL parameters, ESP defaults
**Lint result:** <file>: clean
**Attribution readout:** model, lookback, coverage caveats, table by channel