README

A UTM Builder fieldtype that generates UTM-tagged share URLs for Statamic entries, directly from the Control Panel.

Tracer adds a UTM Builder fieldtype to any blueprint that turns entry edit screens into a campaign URL builder. Think of it as Google's Campaign URL Builder baked into Statamic, so editors can grab a ready-tagged link without leaving the entry they're publishing.

Three sections in one field:

Social: one Copy button per platform (X, LinkedIn, BlueSky, Threads by default; configurable).
Newsletter: one tagged link per newsletter, each with its own utm_campaign and optional utm_id. Most entries use one; a post featured in several newsletters can have a row for each.
Paid Ads: free-form utm_source / utm_medium plus utm_campaign / utm_term / utm_id.

All three share a single utm_content value (defaults to the entry slug; can be overridden per-entry). Inputs auto-normalize to lowercase with underscores so your analytics stays consistent.

Installation

composer require d3creative/statamic-tracer

Then add a Tracer (UTM Builder) field to any blueprint via the Statamic CP. The field renders on the entry edit screen for any entry whose collection produces a public URL.

Configuration

Tracer is configured in two places: platforms and UTM defaults are site-wide, and which sections appear is per blueprint.

Site-wide settings

In the CP, go to Addons → Tracer (or Settings beside Tracer in the addon list). These apply to every Tracer field on the site, so a platform added here appears on every blueprint at once. Values save to resources/addons/statamic-tracer.yaml, which is version-controlled like your blueprints.

Social platforms controls the Copy buttons in the Social section, one button per row, in table order:

Column	What it does
Label	The text shown on the button, e.g. `LinkedIn`.
utm_source	The `utm_source` value in the copied URL, e.g. `linkedin`.

Add a platform: click Add platform and fill in both columns, e.g. Facebook / facebook.
Remove a platform: delete its row.
Reorder: drag rows into the order you want the buttons to appear.

A few things to know:

utm_source is used exactly as typed. It isn't lowercased or normalised like the per-entry inputs, so enter it the way you want it to appear in your analytics (lowercase is recommended).
Give each platform a unique utm_source. Two rows with the same value will clash in the UI.
If you delete every row, the field falls back to the defaults (X, LinkedIn, BlueSky, Threads). To hide social buttons entirely, turn off Show Social section on the field.

Social utm_medium sets the utm_medium shared by every social button (default social).

Newsletters works the same way as the platforms table: Label + utm_source, one row per newsletter a client sends, defaulting to a single Newsletter / newsletter row. On an entry, editors pick from this list rather than typing a source, which is what keeps tech_weekly from becoming techweekly on a post two years later. Adding a newsletter here makes it available on every entry at once.

Newsletter utm_medium (default email) is shared by all of them; campaigns and IDs are set per entry.

Per-field settings

Open the blueprint containing your Tracer field and click the field. The only settings there are which sections to show:

Setting	Default
Show Social section	On
Show Newsletter section	On
Show Paid Ads section	Off

Paid Ads is off because most entries are never advertised and it's the busiest section. Turn it on for blueprints that run paid campaigns. An entry that already has paid values saved shows the section whatever the toggle says, so existing campaign data is never hidden.

In blueprint YAML:

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

How values persist

The field stores a nested object on the entry:

{
    "content": "european_accessibility_act_compliance_websites",
    "newsletters": [
        { "source": "tech_weekly", "campaign": "may_offer", "id": "nl_042" },
        { "source": "partner_digest", "campaign": "june_roundup", "id": null }
    ],
    "paid": { "source": "google", "medium": "cpc", "campaign": null, "term": null, "id": null }
}

When every input is empty the field stores null, so blueprints without active campaign data stay clean.

Upgrading from 1.x

Version 2.0 moves platforms and UTM defaults from the field config to site-wide addon settings. This is a breaking change, so update the constraint deliberately:

composer require d3creative/statamic-tracer:^2.0

What to expect:

Customised platforms revert to the defaults (X, LinkedIn, BlueSky, Threads) until you re-enter them under Addons → Tracer. Copy them across from your blueprint YAML before upgrading if you've changed them. The same applies to social_medium, newsletter_source and newsletter_medium.
Paid Ads is now off by default. Fields that never set paid_enabled will hide the section. Set paid_enabled: true on the field to bring it back. Entries that already have paid values saved keep showing the section either way, so no campaign data becomes unreachable.
Newsletters are now a list. An entry's newsletter: { campaign, id } loads as a single row and is rewritten as newsletters: [ ... ] the next time the entry saves, so nothing needs migrating by hand. The row keeps its campaign and ID, and uses the first newsletter configured under Addons → Tracer. Add the client's other newsletters there before editors start tagging for them.
Old field config is ignored, not removed. platforms, social_medium, newsletter_source and newsletter_medium can be deleted from your blueprint YAML once you've moved the values over.

Requirements

PHP 8.3+ (Statamic 6 requires Laravel 12.40+/13, which needs 8.3)
Statamic 6.x

Support

This addon is maintained by D3 Creative. For enquiries about managed Statamic maintenance, visit d3creative.uk/services/statamic-maintenance.

License

Released under the MIT License.

d3creative / statamic-tracer

Package info

Security

Statistics