Show different widgets by traffic source (UTM)

Use Display tab’s UTM dimension (Pro feature) to switch display by traffic source. Common scenarios:

• TikTok visitors see exclusive coupons
• Email visitors see returning-customer thank-you widget
• Google Ads visitors see product differentiation / trust badges

Steps

1. Create multiple widgets

Create one widget per traffic source (use Reuse widget to speed setup).

2. Configure UTM dimension for each

Enter Display tab → UTM → set Include / Exclude.

UTM row	Purpose
utm_source	Traffic source (tiktok / google / facebook / email, etc.)
utm_medium	Medium (cpc / social / email / referral, etc.)
utm_campaign	Campaign name (blackfriday / launch / valentines, etc.)
utm_term	Keywords (search ads)
utm_content	Creative ID (distinguish different assets in same campaign)

Custom UTM rows (e.g. utm_id, non-standard) can be added.

Image: UTM dimension config (5 standard rows + custom rows)

3. Use corresponding utm params in placement channels

In ad / email links, attach utm params:

https://shop.com/products/foo?utm_source=tiktok&utm_campaign=blackfriday

4. Verify with Simulator

In Display tab’s right Simulator sidebar, paste a real link with utm in the URL field. Tip: “Paste a real link to auto-parse page type + UTM params (utm_source / medium / campaign etc.).”

Image: Simulator sidebar URL field filled, real-time match feedback

UTM session persistence (important)

Real visitors rarely keep UTM params across page navigations. The system records UTM on the landing page (the first page with UTM) into sessionStorage, and subsequent pages fall back to it (commit 599c1ec):

1. Customer enters from TikTok link → URL has utm_source=tiktok
   ↓ widget.js writes sessionStorage["__TTB_UTM__"] = { utm_source: "tiktok", ... }
2. Customer clicks other links in the store (e.g. product detail page)
   ↓ URL no longer has UTM
   ↓ evaluator falls back to sessionStorage
3. UTM dimension still matches utm_source = tiktok rule
4. Customer closes tab → session ends → UTM history cleared

This means merchants don’t worry about “customer lost UTM after one ad click and second page view” — session-wide persistent.

UTM matching rules

Case	Behavior
Multiple values in same UTM row	OR — any match wins (e.g. utm_source includes tiktok OR instagram, either source matches)
Different UTM rows	AND — all must match (e.g. utm_source = tiktok AND utm_medium = social)
Include vs Exclude	Within a row, exclude precedes include (first check exclude list, then include)
UTM dimension not configured	Inactive — widget visible to all traffic sources

UTM combination with other dimensions

UTM dimension AND-combines with other 8 dimensions. For example:

• UTM = tiktok + Pages = Product page = widget shows only for TikTok visitors on product pages