TDS Setup Guide

Conditional traffic routing at the Cloudflare edge — without writing or operating Worker code yourself. Geo, device, bot detection, UTM parameters, and A/B-tested experiments, all driven from a form.

What You Are Building

A TDS rule lives on a Cloudflare Worker attached to your site’s primary domain and runs on every request. The Worker is generated and deployed by 301.st into your own Cloudflare account.

Rules come in two families — Smart Shield for filtering on request signals (geo, device, bot detection), SmartLink for routing on URL parameters (utm_source, fbclid, gclid). Both live on the same site and are evaluated in priority order.

Smart Shield vs SmartLink

The two rule families are not different products — they are two ways of expressing the same rule. The split is about what triggers the match.

Smart Shield

Filter & defend

Matches on every request using signals Cloudflare attaches to the request itself — country, device, OS, browser, bot detection.

Use it when:

  • You need to block or whitewash bots before they reach your offer.
  • You want to restrict a campaign to specific countries or devices.
  • You want mobile and desktop visitors to land on different prelanders.

Presets S1–S9: Bot Shield, Geo Filter, Mobile Redirect, Desktop Redirect, Geo + Mobile, Cloaking Standard, AI Guard, Datacenter Cloak, Geo Origin Routing. Bot categories and the bot presets: Bot filtering.

Stats: the Streams table shows per-rule click counts (today / total) for Smart Shield rules, the same as SmartLink.

SmartLink

Route by source

Matches only when the URL carries tracking parameters — utm_source, utm_campaign, fbclid, gclid, or any param you nominate.

Use it when:

  • You need different prelanders for Facebook (fbclid) and Google (gclid) traffic.
  • You want to split traffic by utm_campaign or sub-id.
  • You want to A/B-test variants depending on the traffic source.

Presets L1–L3: UTM Split, Facebook Traffic, Google Traffic.

Stats: SmartLink rows show click totals and trend in the Streams table when traffic is counted.

Both rule types live on the same site and are evaluated in priority order — Smart Shield rules typically run first (they catch unwanted traffic regardless of URL), then SmartLink rules sort the rest by source.

What a Rule Can Match and Do

  • Conditions: Smart Shield uses request signals (country, device class, bot detection); SmartLink uses URL signals (UTM source/campaign, path regex, referrer, click IDs/sub-IDs). Keep the families separate so rules are easier to debug.
  • Actions: redirect (301/302), block, pass-through to origin, maintenance page, or multi-armed bandit (MAB) redirect — Thompson Sampling, UCB, or Epsilon-Greedy variants automatically rebalance traffic toward the best-performing target as data comes in.
  • Build mode: start from a preset (Smart Shield S1–S9, SmartLink L1–L3) or go Manual for full control. A sandbox preview lets you replay test URLs against the rule before sync — verify the match before the rule reaches the edge.

TDS or a Plain Redirect?

Use a redirect for unconditional moves: domain parking, path moves, vanity URLs, maintenance mode. It is the more battle-tested surface.

Use TDS when the destination depends on the request: a slug, a country, a device, a UTM tag, or a traffic split.

Single Pool or Geo-aware?

When the action is MAB redirect, you choose how destination variants are grouped.

Single pool

One shared list of destination URLs for all matching traffic. Use it for a simple global split where country does not matter — for example testing offer-a.com vs offer-b.com everywhere.

Geo-aware

Separate variant pools per country group. Use it when different groups should get different offers — for example tier1 (US, GB, CA) → Offer A / B, latam (BR, MX) → Offer C / D, default → fallback.

Each Geo-aware segment has a name (such as tier1 or default), optional country codes (such as US, GB, CA), and one or more destination variants. Leave countries empty on one segment to make it the fallback — only one fallback is allowed.

Switching from Geo-aware back to Single pool discards the country segments and their variants, so the app asks you to confirm first.

Before You Start

  • A connected Cloudflare integration with the target domain synced into 301.st.
  • A site whose primary domain is the host that will receive traffic (for example go.example.com).
  • The reflink or destination URL you want matched traffic to land on.

Create Your First Rule

Example: send https://go.example.com/landing to a partner URL while everything else passes through.

  1. Open the site, go to the Streams tab, and click New rule.
  2. Pick a preset (Smart Shield or SmartLink) or choose Manual for full control.
  3. Give the rule a name and a priority. Rules are checked from highest priority down, and the first match wins.
  4. Add a path condition with the regex for your slug (see the next section) and set the action to a 301/302 redirect to your destination URL.
  5. Save the rule. It is stored in 301.st but not yet live on the edge.
  6. Open the rule and press Sync to push it to the Cloudflare Worker. Syncing happens from the rule drawer — a saved rule does nothing until it is synced.

How Path Matching Works

The path field is a raw regular expression. The Worker runs new RegExp(path).test(url.pathname) — an unanchored substring match on the pathname only. The query string and host are never matched.

  • /landing — matches any pathname that contains /landing, including /landing, /landing-page, and /go/landing.
  • ^/landing$ — matches only the exact pathname /landing.
  • ^/review/ — matches any pathname that starts with /review/.
  • .* — matches every request. This is a catch-all.

Regex is not glob. /landin* does not mean "starts with landin" — * repeats the previous character, so it means /landi with zero or more trailing n. For "starts with" use ^/landing; for an exact match use ^/landing-page$.

Because evaluation is priority-first and first-match-wins, a catch-all (.*) rule must have the lowest priority, or it will swallow traffic before more specific rules are reached.

Leaving the path field empty also matches every request — treat an empty path like a catch-all.

Macros in the Destination URL

The destination URL can carry macros, and the Worker replaces them with the visitor's own signals before redirecting. They work in the Action URL of a redirect rule and in every variant URL of a SmartLink rule, including geo-aware pools. The rule drawer has a row of chips under each URL field — click one to insert it.

{country}
Two-letter country code — US, DE, BR — or XX when Cloudflare cannot determine it.
{device}
Either mobile or desktop. There is no tablet value; an iPad counts as desktop.
{os}
windows, macos, linux, android, ios, or unknown.
{browser}
chrome, firefox, safari, edge, opera, or unknown.
{path}
The path the visitor requested on your primary domain.
{host}
The primary domain that received the request.
{clickid}
Our raw click id, 32 hex characters. It is not the attribution key: a postback that returns it does not match the click. Put it only in a separate field a network asks for — in the parameter your postback source reads, the Worker writes the signed token itself and replaces the macro.
{q.name}
A parameter of the incoming request, by a name of letters, digits and underscores (a name with a hyphen or a dot is not supported): {q.clickid} is the value of ?clickid= on the link the visitor came by. URL-encoded, at most 256 characters, empty when the parameter is missing. Its main use is the traffic source’s click id, passed to the network in a second field — see Postbacks → Postback to the Traffic Source.

A macro may appear as often as you need — in the path and again in a tracking parameter — and every occurrence is replaced: https://offer.com/{country}/?geo={country}&d={device} becomes https://offer.com/DE/?geo=DE&d=mobile for a German visitor on a phone.

An unknown macro is left exactly as written. There is no error and no fallback, so a typo like {coutry} travels to your partner literally, inside a URL that looks parameterised. The drawer warns about tokens it does not recognise — do not dismiss that warning.

Companion Tool: Geo Tier Builder

Geo Tier Builder is a free browser extension we maintain for building the inputs TDS rules need.

  • Geo lists: assemble tiered country lists (T1/T2/T3, regions, EU/EEA, BRICS) and export them for a country condition.
  • Regex helper: the Regex tab generates and live-tests a TDS path pattern from plain slugs, with exact / prefix / contains / ends / catch-all modes — paste sample URLs and see what matches before you save the rule.
Get Geo Tier Builder

It runs entirely in your browser and never sees your 301.st account.

FAQ

I created a rule but nothing happens. Why?

A saved rule is not live until you sync it. Open the rule drawer and press Sync to push it to the Cloudflare Worker.

Why does my /landin* pattern not behave like a wildcard?

The path is a regular expression, not a glob. Use ^/landing for "starts with", or the regex helper in Geo Tier Builder to generate a correct pattern.

My catch-all rule blocks everything else. How do I fix it?

Catch-all (.*) matches every request. Give it the lowest priority so more specific rules are evaluated first — rules run priority-first, first match wins.

Where do TDS rules execute?

On a Cloudflare Worker at the edge, attached to the site’s primary domain, on every request to that host.

Smart Shield or SmartLink — which should I use?

If the visitor URL carries tracking parameters (utm_source, fbclid, gclid) and you want to route based on them, use SmartLink. For everything else — filtering bots, splitting by country or device, blocking unwanted traffic — use Smart Shield. Both types can live on the same site; they are evaluated in priority order.

Related Guides

Smart Shield vs SmartLink Bot filtering Getting started Cloudflare integration Domain management Projects and sites Redirects