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

TDS routes incoming traffic by conditions that simple 301/302 redirects cannot express. Rules run on a Cloudflare Worker attached to a site's acceptor domain and are evaluated on every request.

Rules come in two families — Smart Shield for filtering on request signals, SmartLink for routing on URL parameters. The next section breaks down which one to pick.

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–S5: Bot Shield, Geo Filter, Mobile Redirect, Desktop Redirect, Geo + Mobile.

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: path, country, device, bot detection, UTM source, UTM campaign, or referrer.
  • Actions: redirect (301/302), block, pass through, or MAB redirect.
  • Build mode: start from a preset, or build manually with full control.

TDS or a Plain Redirect?

Use a redirect for unconditional moves: domain parking, path moves, vanity URLs, maintenance mode.

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 acceptor domain is the host that will receive traffic.
  • 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 or choose Manual for full control.
  3. Give the rule a name and a priority. Highest priority down, first match wins.
  4. Add a path condition and set the action to a 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.

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.

  • /landing — matches any pathname that contains /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* means /landi with zero or more trailing n, not "starts with landin". Use ^/landing for "starts with".

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 acceptor domain.
{host}
The acceptor domain that received the request.

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 and export them for a country condition.
  • Regex helper: generate and live-test a TDS path pattern from plain slugs 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.

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.

Where do TDS rules execute?

On a Cloudflare Worker at the edge, attached to the site's acceptor 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 Getting started Cloudflare integration Domain management Projects and sites Redirects