=== RedFoX UTM Link Builder ===
Contributors: redfoxbusiness
Tags: utm, utm builder, campaign tracking, analytics, email marketing
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.4.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build clean UTM links in WordPress – with a naming convention, campaigns, a link history and a checker that catches typos before you send.

== Description ==

**Clean UTM links. Reports that add up.** RedFoX UTM Link Builder is the UTM builder inside your WordPress dashboard. Pick a page, a channel and a campaign – and get a clean, consistent tracking link in seconds, copied to your clipboard and saved in a searchable history.

Campaign reports only add up when every link is named the same way. One `Facebook` instead of `facebook`, one campaign spelled two ways, one `?` too many – and your analytics split into rows nobody can add up again. The builder follows the [RedFoX UTM Convention](https://www.redfox-business.com/utm-convention/) (free PDF), so everyone on your team builds links the same way, without typos.

= Why people use it =

* **Same naming across your team:** fixed channels, sources and campaign names instead of free typing – everyone builds links the same way.
* **No more typos:** capitals, umlauts and spaces are fixed automatically, and the link checker finds mistakes in links you got from somewhere else.
* **All links in one place:** every link you build is in the history, with campaign, date, author and note.
* **Every button measurable:** short name and click purpose end up in `utm_content`, so you see which email and which button brought the visit.
* **Quick to use:** choose instead of type – the link is ready in a few clicks.
* **No lock-in:** the links are plain addresses. They keep working even if you deactivate the plugin.

= Features =

* **Build links step by step:** choose a page of your site (search field) or any address, then channel, source, campaign and click. The link appears live and is copied with one click.
* **Channels of the convention built in:** email, organic social, social ads, video and search ads – each with its sources and placements, explained right in the drop-down. Add your own channels (e.g. `referral`, `sms`, `print`).
* **Campaigns:** create them with a naming helper (`phase_offer_year_month`), describe what they are for, archive them when they are over. Campaign names cannot be changed once links carry them.
* **utm_content made easy:** short name + click purpose, e.g. `email_invite_cta_register` – so you see later which email and which button brought the visit.
* **History:** every link is saved with date, author and note. Search, filter by campaign, copy again.
* **Protection against mistakes:** the same link already exists → it is simply copied again. Same short name in the same campaign but a different target → you are asked first. Capitals, umlauts and spaces are converted automatically.
* **Link checker:** paste any link (e.g. from an email) and see what is wrong: a second `?`, spaces, `&amp;` from HTML source, unknown sources or campaigns, a misspelled contact placeholder.
* **Contact ID for emails (optional):** adds `sid=%SUBSCRIBERID%` (ActiveCampaign), `{{contact.id}}` (FluentCRM) or your own placeholder to email links, so a live chat or a one-click sign-up recognises who clicked. Off by default.
* **Export & import** of campaigns and links as JSON – e.g. to move them to another site.
* Ready for translation.

= Who it is for =

Small teams, coaches, course creators and agencies who send newsletters, post on social media and run ads – and want reports in Matomo, Google Analytics or any other tool that add up.

= What it does not do =

It builds and stores links. It does not shorten or redirect links, does not count clicks and does not track visitors. The links work on their own – even if you deactivate the plugin.

== Privacy ==

The plugin does not contact any external service, sets no cookies and tracks nothing on your website. Links, campaigns and settings are stored in your WordPress database only.

The optional contact ID adds a placeholder to email links that your email system replaces with the recipient's contact number. It ties a visit to a person – only switch it on if your privacy policy covers it.

The admin page links to the RedFoX UTM Convention on redfox-business.com. Nothing is loaded from there; it is a normal link.

== Installation ==

1. Install and activate the plugin.
2. Go to Tools → UTM Link Builder.
3. Create your first campaign (step 3), choose a target and a channel – done. Copy the link with “Save & copy”.
4. Optional, under Settings: choose your email system for the contact ID, switch `placement` off if you do not need it, add your own channels.

== Frequently Asked Questions ==

= What is the RedFoX UTM Convention? =

A short set of rules for UTM parameters that keeps reports clean: `utm_medium` is the channel (email, organic_social, paid_social …), `utm_source` the specific origin (newsletter, instagram …), `utm_campaign` the initiative, `utm_content` the single click. Read it online or download the PDF: [English](https://www.redfox-business.com/utm-convention/) · [Deutsch](https://www.redfox-business.com/utm-konvention/).

= Can I use my own values? =

Yes. Sources, placements, prefixes and click purposes can be edited in the settings, and you can add your own channels. Any address can be the target, not only pages of your site.

= What is "placement"? =

An extra parameter that says where the link sits (e.g. `email_button` or `bio`). It is not a standard UTM parameter – analytics tools only show it if you set it up as a custom dimension. You can switch it off in the settings.

= Do my links stop working if I deactivate or delete the plugin? =

No. The links are normal addresses with parameters; they do not depend on the plugin. Deleting the plugin keeps your history and campaigns too – unless you tick “Remove all links, campaigns and settings when the plugin is deleted” in the settings.

= Who can build links? =

Everyone who can edit posts. Settings, export and import are for administrators. Developers can change the capability with the filter `redfox_utm_capability`.

= Should I build Meta ad links here? =

No. In Meta ads, use Meta's own placeholders (e.g. `{{site_source_name}}`, `{{ad.name}}`) so Meta fills them in. The link checker knows the values Meta uses (`fb`, `ig`, `msg`, `an`).

== Screenshots ==

1. Build a link step by step – live preview on the right.
2. History with search and campaign filter.
3. Campaigns: create, describe, archive.
4. The link checker finds typos before you send.
5. Settings: email system, placement, channels, click purposes.

== Changelog ==

= 1.4.1 =
* First public release on WordPress.org.
* All internal names use the prefix redfox_utm_. Links and campaigns from 1.4.0 or older: export them before the update and import them afterwards.
* Translations come from translate.wordpress.org.

= 1.4.0 =
* English as the base language, German included.
* Default values follow the site language (English or German, as in the convention PDFs).
* Add your own channels; switch the placement parameter off.
* Contact ID off by default, with a privacy note.
* Short introduction for new installs.

= 1.3.0 =
* Renamed from "RedFoX Link-Baukasten". Data stays.

= 1.2.0 =
* Labels and help per channel (email, social, video, ads).

== Upgrade Notice ==

= 1.4.1 =
First public release. Coming from 1.4.0 or older? Export your links and campaigns first (Settings → Export) and import them after the update.
