EVAOO ATTRIBUTION ENGINEERING SPECIFICATION · REV 2026.11

UTM Best Practices & GA4 Attribution Engineering Spec

The production-grade specification for DTC brands, media buyers, and analytics engineers: eliminate GA4 Unassigned traffic, deploy dynamic ad macros, and enforce a single source of truth.

8 Params

5 Core + 3 GA4 v2

Unassigned Leak

24 SOPs

Verified Rules

Open UTM Builder Pro Shopify GTM Gen

00 / INTERACTIVE DIAGNOSTIC CONSOLE

Live UTM Hygiene Sanitizer & GA4 Channel Group Console

Select a sample or edit parameters live

ga4-channel-router — zsh

Active Scenario: Fatal issues: (1) FB_Boost_Ad falls into GA4 Unassigned; (2) & and spaces break URL parsing; (3) # truncates query; (4) Email address violates GA4 PII policy!

base_url

utm_source *

utm_medium *

utm_campaign *

utm_id (GA4 Cost Key)

utm_content

utm_term

GA4 CHANNEL GROUP VERDICT⚠️ Unassigned (未分配黑洞)

Attribution Failure: GA4 Default Channel Grouping does not recognize utm_medium="FB_Boost_Ad"! Traffic will be dumped into Unassigned.

LINT AUDIT (6 warnings)

[ERR]Attribution Failure: GA4 Default Channel Grouping does not recognize utm_medium="FB_Boost_Ad"! Traffic will be dumped into Unassigned.
[WARN]Uppercase characters detected: GA4 is case-sensitive (Facebook vs facebook splits rows).
[WARN]Whitespace detected: Spaces turn into %20 and break links. Replace with underscores (_).
[ERR]Reserved characters (& / # / % / +) detected: # and & inside values truncate UTM parameters!
[ERR]GA4 PII Violation: Email (@) detected! Sending PII to Google Analytics risks property termination.
[WARN]Missing utm_id: Required by GA4 as the primary join key for non-Google Cost Data Import.

AUTO-SANITIZED URL (→ GA4: Paid Social)

https://evaoo.com/collections/ebike?utm_source=facebook&utm_medium=paid_social&utm_campaign=2026_summer_sale_and_promo&utm_id=camp_001&utm_content=video_ad_1_916

01 / URL ANATOMY & 8-PARAMETER SPECIFICATION

Anatomy of a Production Tracking URL & 8-Parameter Ledger

In GA4, a complete tracking URL combines your clean landing page with 5 core UTM keys and 3 extended v2 dimensions:

LIVE URL ANATOMY BREAKDOWN

https://evaoo.com/collections/ebike?utm_source=facebook&utm_medium=paid_social&utm_campaign=us_conv_tof_bfcm_202611&utm_id=fb_120210948&utm_content=vid_ugc_hook1_9x16&utm_term=lal_1pct_us

utm_sourceRequired

GA4: Session source

Where did traffic come from?

Identifies the specific advertiser, search engine, or publisher platform sending the traffic.

DO:google, facebook, instagram, tiktok, klaviyo, youtube, impact

NO:Facebook.com, FB_Ads, google_cpc, 公众号

utm_mediumRequired

GA4: Session medium

How did it arrive?

Directly controls GA4 Default Channel Grouping routing. Non-standard values fall into Unassigned.

DO:cpc, paid_social, email, affiliate, display, social, sms, referral

NO:paid, boost, kol_video, edm, banner_ad

utm_campaignRequired

GA4: Session campaign

Which strategic campaign?

Structured taxonomy encoding region, objective, funnel stage, promo theme, and launch month.

DO:us_conv_tof_bfcm-ebike_202611, de_search_brand_exact_2026q4

NO:2026 Black Friday & Cyber Monday!, test1

utm_idGA4 Join Key

GA4: Session campaign ID

Cost Data Import Join Key

Mandatory primary join key for importing non-Google ad spend CSVs into GA4 to calculate ROAS.

DO:fb_120210948, gads_2094817, tt_179402819

NO:(留空不填，导致无法在 GA4 对账 Meta/TikTok 广告消耗)

utm_contentCreative / Slot

GA4: Session manual ad content

Which creative or CTA?

Differentiates video hooks, creator variants, ad placements, or multiple CTA buttons inside one email.

DO:vid_range-test_ugc-alex_9x16, btn_hero_claim_10off

NO:video#1, link_a, 红色按钮

utm_termKeyword / Audience

GA4: Session manual term

Which keyword or AdSet?

Tracks paid search keywords + match types, or Ad Set audience targeting segments in Paid Social.

DO:carbon_commuter_ebike_e, lal_1pct_purchasers_us

NO:[email protected] (严禁夹带用户隐私数据)

utm_source_platformGA4 v2 Extended

GA4: Session source platform

Which buying platform?

Identifies the buying platform directing traffic (e.g., Google Ads vs DV360 vs Meta Ads).

DO:meta_ads, google_ads, tiktok_ads, dv360

NO:ios_app, desktop_web

utm_creative_format & utm_marketing_tacticGA4 v2 Extended

GA4: Creative format / Tactic

Modality & bidding tactic

Describes creative modality (reel_9x16, carousel) and bidding tactic (remarketing, prospecting).

DO:reel_9x16 / prospecting_broad, carousel_4card / dynamic_retargeting

NO:good_video / cheap_clicks

02 / GA4 DEFAULT CHANNEL GROUPING ROUTING TABLE

GA4 Default Channel Grouping Regex Dictionary

GA4 does not guess custom mediums. If your utm_medium fails the official regex rules below, conversions are dumped into Unassigned:

GA4 Channel Group	Official GA4 Regex Logic	Fatal Mistakes (Unassigned)
Paid Social (付费社交) source: facebook, instagram, tiktok, pinterest, reddit, linkedin	Source ∈ Social Sites AND Medium =~ ^(paid_social\|paidsocial\|paid-social\|cpc\|ppc)$	✗ social_paid, fb_ad, boost, ig_paid, kol_boost
Paid Search (付费搜索) source: google, bing, yahoo, duckduckgo, baidu	Source ∈ Search Sites AND Medium =~ ^(cpc\|ppc\|retargeting\|paidsearch)$	✗ search_ad, sem, google_cpc, paid_search (注意带下划线的 paid_search 不在默认正则内)
Cross-network (跨网络 / PMax) source: google	Campaign =~ "cross-network" OR Google Ads PMax / Demand Gen Auto-Tag	✗ pmax, performance_max (关闭 gclid 时需在 campaign 含 cross-network)
Email (邮件营销) source: klaviyo, mailchimp, omnisend, newsletter	Source OR Medium =~ ^(email\|e-mail\|e_mail\|e mail)$	✗ edm, mail, klaviyo_flow, drip_campaign (写 edm 在 GA4 中 100% 掉入 Unassigned)
Affiliates (联盟与红人分佣) source: impact, shareasale, partnerboost, creator_handle	Medium =~ ^(affiliate\|affiliates)$	✗ kol, influencer, pr, partner, cpa_link
Display (展示与程序化横幅) source: google, criteo, taboola, outbrain, adroll	Medium =~ ^(display\|banner\|expandable\|interstitial\|cpm)$	✗ gdn, image_ad, retargeting_banner
Organic Social (自然社媒与主页) source: youtube, instagram, tiktok, x, facebook, linktree	Source ∈ Social Sites OR Medium =~ ^(social\|social-network\|social-media\|sm)$	✗ bio_link, organic_post, profile_url, yt_desc
SMS (短信与私域触达) source: postscript, attentive, twilio	Source OR Medium =~ ^sms$	✗ text_message, mms, mobile_push

03 / DYNAMIC URL MACROS BY AD PLATFORM

Meta, Google & TikTok Ads Dynamic URL Macros

Stop manually typing UTMs for every ad. Paste these dynamic tracking templates into Meta, Google, and TikTok Ads Manager:

Meta Ads (Facebook / Instagram)Ad Level → URL Parameters

utm_source={{site_source_name}}&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_id={{campaign.id}}&utm_content={{ad.name}}_{{placement}}&utm_term={{adset.name}}&utm_source_platform=meta_ads

Where to paste: Meta Ads Manager → Ad Level → Tracking → URL Parameters field (do not include the leading ?).

→ utm_source

Auto-resolves publisher platform (fb, ig, msg, or an)

Sample output: ig

→ utm_campaign

Campaign name (use lowercase + underscores in Ads Manager)

Sample output: us_conv_prospecting_bfcm_202611

→ utm_id

Unique Campaign ID (required for GA4 Cost Data Import)

Sample output: 12021094857392

→ utm_term

Ad Set name (typically represents audience targeting)

Sample output: lookalike_1pct_purchasers_us

→ utm_content

Ad creative name (identifies video/image hook & variant)

Sample output: vid_ugc_unboxing_hook1

→ utm_content

Exact ad placement (e.g., Instagram_Reels, Facebook_Feed)

Sample output: Instagram_Reels

04 / ENTERPRISE NAMING TAXONOMY PIPELINE

Structured Campaign & Creative Taxonomy Pipeline

Core principle: Delimit taxonomy segments with underscores (_) and join multi-word tokens with hyphens (-) so analysts can run SPLIT(utm_campaign, "_") in SQL:

A. utm_campaign 5-Segment Campaign Pipelineus_conv_tof_bfcm-carbon-ebike_202611

01 · [region]

ISO Region

us / uk / de / fr / eu / global

02 · [objective]

Ad Objective

conv / lead / traffic / aware

03 · [funnel]

Funnel Stage

tof (拉新) / mof / bof (再营销) / ret

04 · [promo-prod]

Promo & Product

bfcm-ebike / spring-sale / evergreen

05 · [yyyymm]

Launch Period

202611 / 2026q4 / 2026w47

B. utm_content 4-Segment Creative Pipelinevid_range-test_ugc-alex-v2_9x16-30s

01 · [format]

Creative Format

vid (视频) / img (单图) / car (轮播) / dpa

02 · [hook-angle]

Core Hook Angle

range-test / unboxing / price-drop / hill-climb

03 · [creator-cut]

Creator & Cut

ugc-alex-v2 / studio-main-v1 / kol-liam

04 · [ratio-len]

Aspect & Length

9x16-30s / 4x5-15s / 1x1-static

05 / ATTRIBUTION DEBUGGING & INCIDENT RESPONSE

6 Fatal Attribution Disasters & Engineering Fixes

When Direct traffic spikes or paypal.com steals conversion credit in GA4, audit these 6 engineering failure points:

Critical · Wipes Paid ROAS

Using UTMs on Internal Links (Destroys Original Attribution)

Clicking an internal banner with ?utm_source=hero_banner immediately terminates the user’s active Paid Social session and starts a new session, wiping out original ad attribution.

Engineering Remediation

Never use utm_* on internal site links. Use GA4 select_promotion events or non-UTM query keys (?promo_slot=hero_1) instead.

❌ ?utm_source=hero_banner → ✅ ?promo_slot=hero_banner_1 (配合 GA4 select_promotion 事件)

High · Turns Paid Traffic into Direct

Server 301 Redirects Stripping Query Strings

Ad destination URLs that trigger HTTP->HTTPS, non-www->www, or trailing-slash 301 redirects often drop query strings if server rules omit $args.

Engineering Remediation

Always test ad URLs with `curl -sIL` before launch to verify the final 200 destination preserves all query parameters.

curl -sIL "https://your-domain.com/landing?utm_source=test" | grep -iE "^(http|location)"

High · Revenue Credited to PayPal

Payment Gateway Redirect Hijacking Conversions

Returning from external payment gateways (paypal.com, stripe.com) to /thank_you triggers a new referral session if not excluded.

Engineering Remediation

Add all external checkout domains to GA4 Unwanted Referrals so returning buyers stay in their original ad session.

GA4 → Data Streams → Configure tag settings → List unwanted referrals → paypal.com, stripe.com, shop.app, klarna.com

Medium-High · Click ID Loss

iOS 17+ Link Tracking Protection Stripping Click IDs

iOS 17+ Link Tracking Protection strips user-level click IDs (fbclid, gclid, ttclid) in Safari/Messages/Mail, but preserves standard aggregate UTM parameters.

Engineering Remediation

Always deploy standard UTM parameters alongside auto-tagging (gclid/fbclid) as an iOS 17+ resilient attribution fallback.

Auto-tagging (gclid/fbclid) = ON + Standard UTM Tracking Template = ON (双轨冗余)

Medium · Dark Social Blindspot

URL Shorteners & In-App WebViews Dropping Context

Links clicked inside WhatsApp, WeChat, Telegram, or Discord open in WebViews that strip HTTP Referer headers, inflating Direct traffic.

Engineering Remediation

Always embed full UTM parameters BEFORE shortening URLs, and tag all community/PDF/WhatsApp links explicitly.

Long URL + Full UTMs ──(Shorten)──> bit.ly/xxx ──(301)──> Landing Page with UTMs Intact

Compliance · Property Deletion Risk

Passing Email or Phone Numbers in UTMs (GA4 PII Termination)

Accidentally passing {{subscriber.email}} or phone numbers in URL parameters violates Google Analytics PII terms and exposes PII to third-party scripts.

Engineering Remediation

Only pass anonymized segment tags or hashed IDs in URLs; never pass raw emails, names, or phone numbers.

❌ [email protected] → ✅ ?utm_term=seg_vip_loyal_tier1

06 / 24-POINT EXECUTION CHECKLIST

24-Point Cross-Channel UTM Execution Checklist

01. Never Use Raw & or # Inside Parameter Values

[Syntax Rule]

& splits key-value pairs Prematurely, and # starts a URL fragment that browsers never send to analytics servers.

✗ utm_campaign=black&white_#1

✓ utm_campaign=black_and_white_no1

02. Enforce Strict Lowercase Casing

[Syntax Rule]

GA4 is strictly case-sensitive. Facebook, facebook, and FACEBOOK split metrics across three separate rows.

✗ utm_source=Facebook&utm_medium=Paid_Social

✓ utm_source=facebook&utm_medium=paid_social

03. Eliminate Spaces (%20) with Underscores & Hyphens

[Syntax Rule]

Spaces turn into ugly %20 sequences and break in chat apps. Use _ between fields and - inside compound tokens.

✗ utm_campaign=summer sale 2026

✓ utm_campaign=us_conv_summer-sale_2026

04. Never Tag Internal Site Links with UTMs

[Syntax Rule]

Internal UTMs reset the active session and overwrite original Paid Search / Paid Social attribution.

✗ href="/products/pro?utm_source=home_banner"

✓ href="/products/pro?promo_slot=home_hero_1"

05. Zero PII (Emails, Names, Phones) in URLs

[Syntax Rule]

Passing raw emails or phone numbers in URLs violates GA4 terms of service and triggers GDPR liabilities.

✗ [email protected]

✓ utm_term=segment_vip_tier1_hash89a

06. Place Hash Anchors (#) Strictly at the Very End

[Syntax Rule]

Always append ?utm_source=... before any #section fragment so query parameters are parsed properly.

✗ https://evaoo.com/deal#pricing?utm_source=ig

✓ https://evaoo.com/deal?utm_source=ig#pricing

07. Standardize Paid Social Medium as paid_social

[GA4 Attribution]

Custom mediums like fb_ad or boost fail GA4 regex matching and fall into Unassigned.

✗ utm_source=ig&utm_medium=ig_story_boost

✓ utm_source=instagram&utm_medium=paid_social

08. Use email (Never edm) for Email Marketing

[GA4 Attribution]

GA4 only recognizes email/e-mail/e_mail. Using "edm" dumps 100% of newsletter traffic into Unassigned.

✗ utm_source=klaviyo&utm_medium=edm

✓ utm_source=klaviyo&utm_medium=email

09. Include utm_id for Non-Google Cost Data Import

[GA4 Attribution]

GA4 Cost Data Import requires utm_id (Campaign ID) as a mandatory join key alongside source/medium.

✗ utm_source=tiktok&utm_campaign=uk_bfcm

✓ utm_source=tiktok&utm_campaign=uk_bfcm&utm_id=tt_9021

10. Run Hybrid Auto-Tagging (gclid/fbclid) + Standard UTMs

[GA4 Attribution]

iOS 17+ strips user-level click IDs (gclid/fbclid), making aggregate UTM parameters essential fallback armor.

✗ https://evaoo.com/pro?fbclid=IwAR29x... (无 UTM 兜底)

✓ https://evaoo.com/pro?utm_source=fb&utm_medium=paid_social&fbclid=...

11. Tag Affiliate & Commission KOL Links with affiliate

[GA4 Attribution]

Use utm_medium=affiliate to hit GA4 Affiliates channel group, placing creator handles in utm_content.

✗ utm_source=youtuber_alex&utm_medium=kol

✓ utm_source=impact&utm_medium=affiliate&utm_content=kol_alex

12. Configure Unwanted Referrals for Payment Gateways

[GA4 Attribution]

Exclude paypal.com, stripe.com, and shop.app in GA4 Data Stream settings so checkout redirects keep original UTMs.

✗ Session source/medium = paypal.com / referral

✓ GA4 Unwanted Referrals: paypal.com, stripe.com, klarna.com

13. Tag Organic Bio Links & Posts with utm_medium=social

[Channel Ops]

Separate organic community traffic (utm_medium=social) from paid media (utm_medium=paid_social).

✗ utm_source=instagram_bio&utm_medium=linktree

✓ utm_source=instagram&utm_medium=social&utm_content=bio_link

14. Embed Offline UTMs Inside Packaging & Booth QR Codes

[Channel Ops]

Camera QR scans send no HTTP Referer. Tag QR target URLs so offline scans don’t inflate Direct traffic.

✗ QR → https://evaoo.com/warranty

✓ QR → https://evaoo.com/warranty?utm_source=package_insert&utm_medium=qr_code&utm_campaign=warranty_reg

15. Email Heatmap Tracking via utm_content

[Channel Ops]

Keep source/medium/campaign identical across an email and vary utm_content per CTA block.

✗ 所有按钮共用同一个 utm_campaign 无区分

✓ utm_content=hero_banner vs utm_content=footer_cta_btn

16. Standardize SMS & Text Campaigns with utm_medium=sms

[Channel Ops]

Tag Postscript/Attentive/Twilio links with utm_medium=sms before shortening.

✗ utm_source=postscript&utm_medium=text_msg

✓ utm_source=postscript&utm_medium=sms&utm_campaign=vip_flash_sale

17. Tag Links Embedded Inside PDF Playbooks & Catalogs

[Channel Ops]

Clicks from PDF viewers carry no Referrer header. Tag all embedded links with utm_source=pdf_guide.

✗ PDF link → https://evaoo.com/pricing

✓ PDF link → https://evaoo.com/pricing?utm_source=geo_whitepaper&utm_medium=referral&utm_content=page_12_cta

18. Track B2B Sales & Support Email Signatures

[Channel Ops]

Add subtle UTM tags to corporate email signatures to measure high-intent B2B pipeline contribution.

✗ Signature → https://evaoo.com

✓ utm_source=email_signature&utm_medium=email&utm_campaign=b2b_sales_team

19. Never Swap or Duplicate Source & Medium Semantics

[Governance]

Source is "Where" (noun: google, tiktok); Medium is "How" (pipe: cpc, paid_social). Never swap them.

✗ utm_source=cpc&utm_medium=google

✓ utm_source=google&utm_medium=cpc

20. Audit HTTP 301 Redirect Chains Before Launching Ads

[Governance]

Verify that server 301 redirects (HTTP→HTTPS, locale redirects) preserve query strings intact.

✗ http://evaoo.com/deal?utm_source=fb → 301 → https://evaoo.com/zh/deal (参数丢失)

✓ 直接使用最终 200 状态码落地页 URL 作为广告落点

21. Persist First-Touch UTMs in First-Party Storage / CRM Hidden Fields

[Governance]

Write initial landing UTMs into first-party cookies so multi-session checkouts retain original acquisition credit.

✗ 仅读取当前最后一次结账页面的 URL 参数

✓ 通过 GTM 持久化 first_utm_source 与 last_utm_source 双轨写库

22. Always Append UTMs Before Creating Shortlinks

[Governance]

Appending UTMs to an already-shortened URL often fails during 301 expansion. Tag first, shorten second.

✗ https://bit.ly/3xYz9?utm_source=twitter

✓ 先将含完整 UTM 的长链接传入短链生成器

23. Keep Total URL Length Under 2,000 Characters

[Governance]

Use standardized abbreviations (conv, tof, ret) to keep URLs compact and readable in reporting tables.

✗ utm_campaign=united_states_conversion_top_of_funnel_black_friday_cyber_monday_promotion

✓ utm_campaign=us_conv_tof_bfcm_202611

24. Maintain a Centralized Team Naming Dictionary

[Governance]

Eliminate rogue agency naming by enforcing a shared preset library in UTM Builder Pro.

✗ 投手 A 用 fb / 投手 B 用 facebook / 代理商用 meta_ads

✓ 全团队锁定统一词典：utm_source=facebook & utm_medium=paid_social

Ready to enforce this UTM specification across your team?

Use UTM Builder Pro with built-in hygiene linting and bulk matrix generation.

Launch UTM Builder Pro Shopify 42-Point Pixel Audit