Tracer 2.0: my Statamic UTM builder gets site-wide settings

My Statamic UTM builder, Tracer, has reached version 2.0. The headline change is where the settings live. Social platforms and newsletters have moved out of individual blueprint fields and into one settings screen for the whole site.

If you haven't come across it, Tracer adds a field to an entry's edit screen that builds UTM (Urchin Tracking Module) links. Those are the utm_ tags on the end of a URL that tell your analytics where a visitor came from. Think of Google's Campaign URL Builder, except it already knows the entry's address and sits inside the Statamic Control Panel (CP), so an editor can copy a tagged link without leaving the post they're publishing.

Settings that apply to the whole site

In 1.x, the list of social platforms lived in the blueprint field config. Add Facebook to the Tracer field on a blog post and it existed on blog posts only. A site running Tracer on pages, posts and case studies meant editing the same list three times, or forgetting to.

Version 2.0 moves all of it to Addons → Tracer in the CP: one table of social platforms, one table of newsletters, and the utm_medium each group shares. A platform added there appears on every Tracer field at once. The values save to resources/addons/statamic-tracer.yaml, so they are version-controlled alongside your blueprints rather than buried in a field config. The defaults are X, LinkedIn, BlueSky and Threads.

One entry, several newsletters

A client with more than one newsletter had no good option in 1.x. An entry stored a single campaign and ID, against a single source set in the field config.

Newsletters are now a list. Each row picks a newsletter from the site settings and gets its own utm_campaign and utm_id, so a post that goes out in two different newsletters can be tracked separately. Most entries still use one row, and the newsletter picker stays hidden while only one newsletter is configured, so nothing changes for a site with a single list.

If a newsletter is later removed from the settings, a row still using it keeps working and says so on screen. It does not quietly drop a link an editor has already shared.

utm_source generates from the label

Both settings tables generate utm_source from the label you type. Tech Weekly becomes tech_weekly. It stays editable, with a regenerate button, so you can fix it before any links go out. On an entry, editors pick a newsletter from that list instead of typing a source, which matters more than it sounds.

A utm_source typed by hand in January and again in September is two rows in your analytics, not one.

Changing a source after links are shared splits the traffic between the old value and the new. There is no fixing it after the fact, which is why both tables warn about it, and why generating the value beats retyping it.

Paid Ads is off by default

Paid Ads is the busiest part of the field, with source, medium, campaign, term and ID all free-form, and most entries are never advertised. It is now hidden unless the field asks for it:

-
  handle: tracer
  field:
    type: tracer
    display: Tracer
    paid_enabled: true

An entry that already has paid values saved shows the section either way, so no campaign data becomes unreachable by flipping a toggle.

Upgrading from 1.x

This is a breaking change, so update the constraint deliberately. Four things to know:

• Customised platforms revert to the defaults. Copy them out of your blueprint YAML before upgrading, then re-enter them under Addons → Tracer. The same applies to the old social_medium, newsletter_source and newsletter_medium settings.

• Paid Ads needs turning back on. Any field that should keep showing it needs paid_enabled: true.

• Entry data migrates itself. An old single newsletter loads as one row and is rewritten as a list the next time the entry saves. There is nothing to run by hand.

• PHP 8.3 is the new minimum. 1.x claimed 8.2, but Statamic 6 pulls in Laravel 12.40 or newer, which needs 8.3. The old constraint was never installable.

There is a test suite behind this release too: 12 tests covering how the field reads and stores its values, including every older data shape an entry might still be sitting in. To install or upgrade:

composer require d3creative/statamic-tracer:^2.0

The full list of changes is in the changelog. If you would rather not keep track of which of your addons need updating, that is what my website maintenance covers. I run the updates, test the site and tell you what changed.