UTM Tags
With UmbSocial Pro licensed, the links in your posts can carry UTM parameters, so your analytics tell the networks, and your campaigns, apart. The tags are added as the post goes out to each channel: the post as you wrote it is never changed, and the composer’s previews and character counts show the links as they will go out.
What each field is for
Section titled “What each field is for”| Parameter | What it says | Set | Default |
|---|---|---|---|
utm_source |
Where the click came from: the platform, such as bluesky or linkedin. |
Centrally, for each network. | {network}, locked |
utm_medium |
The kind of channel. | Centrally. | social, locked |
utm_campaign |
The campaign the post belongs to. | On the post (its Campaign field). | Empty: no campaign is added unless a post sets one. Unlocked. |
utm_content |
Tells versions of the same link apart, for example by channel. | On the post, or centrally. | {channel} (the channel’s name), unlocked. |
utm_term is for paid-search keywords and isn’t used.
The source and the medium stay the same across posts, so they are best fixed centrally: analytics such as GA4 are case-sensitive, so LinkedIn and linkedin would be two sources. The campaign changes from post to post, or for a batch of posts, so it is written on the post.
Switch it on
Section titled “Switch it on”Tagging is off on a new site: links go out as written. Switch it on in Settings › UmbSocial › Links (needs ManageSettings):
- Tag outgoing links turns tagging on.
- Your site’s domains lists the domains set up in Umbraco (Content › Culture and Hostnames), read from Umbraco each time the page opens. Each has an on switch, and they are all on by default: links to them are tagged (and shortened, see Short links). Switch a domain off to leave its links as written. The settings keep only the domains you switch off, never a copy of the list, so a domain you add in Umbraco later is included automatically.
- Other hosts lists extra hosts you link to that aren’t Umbraco domains, such as a shop or booking site, one a line (
example.com, withouthttps://or a path; a leadingwww.is ignored). Their links are tagged too, but they are not shortened unless you choose that for a link in a post. A link to any other host is never touched, and neither is a link that isn’thttporhttps. - A table has a default and a lock for each of the four fields.
- Source for each network lets you set a different source for a network (for example
lifor LinkedIn). A network without one uses the source default. Only the networks Social posts to can have one, each once, at most 100 characters.
Select Save in the footer bar (or press Ctrl+S) to save. If you leave the page with changes you haven’t saved, Umbraco asks whether to discard them. A value the server refuses is marked on its field, and a message says why.
A default can use these placeholders, filled in for each channel:
| Placeholder | Becomes |
|---|---|
{network} |
The channel’s network, such as bluesky. |
{channel} |
The channel’s name, such as Company Page. |
{date} |
The post’s scheduled date in the site’s time zone, as yyyy-MM-dd (today’s date for a post with no time yet). |
A default is at most 100 characters, and it can only use those three placeholders.
On a post
Section titled “On a post”When a post has a link, and tagging is on, the composer shows a Link tracking panel under the text:
- Campaign is the composer’s own Campaign field, where you search for a campaign by name or add a new one, as anywhere in UmbSocial. When the campaign is locked centrally, that field shows the central value, read-only, and says why.
- Source, Medium and Content let the post set its own value. Leave one empty to use the default.
- Don’t tag this post’s links sends the post’s links as written.
- Links as they will go out shows each chosen channel’s link with its parameters, or says why a link is left as written.
A locked field is shown disabled with its central value and the note Set centrally: that value is always used, and a value a post has stored for it earlier is ignored. If the campaign is locked, what is written in the Campaign field isn’t used.
The post’s own values are part of the post. Changing one counts as a change to the post, so leaving without saving asks whether to discard it, and Discard puts the saved values back. They are saved when you save the post, whether you save it yourself or the composer saves the draft for you. If they can’t be saved, the post stays unsaved so you can try again: when you save, a message says why and the field is marked; when the composer saves the draft for you, it shows Not saved at the bottom instead.
On a post you can’t change, the fields are read-only, by the same rule as the rest of the post: for example, someone else’s scheduled post when you don’t have the Schedule permission, or a post that is being sent right now.
The composer’s own previews and character counts use the central values (they don’t see the post’s own values); the Links as they will go out list in the panel uses the values you are editing.
While UmbSocial isn’t licensed, the panel and Settings › UmbSocial › Links are hidden. The post’s own values and the settings are kept, and links go out as written until the licence is active again.
How a link is tagged
Section titled “How a link is tagged”For each channel, each field resolves as follows:
- If the field is unlocked and the post has a value, that value. Otherwise the central default (for the source, the network’s own source if you set one, else the source default).
- Placeholders are filled in.
- The value is normalised: trimmed, lowercased, runs of spaces turned into a single
-, and anything outsidea-z 0-9 . _ ~ -dropped.Spring Sale!becomesspring-sale. - A value that is empty after that leaves its parameter off.
The parameters are then added to the link:
- A parameter the link already has is kept, never overwritten (
utm_source=newsletterstays). - The link’s other query parameters and its
#fragmentare kept, in order.
For example, with the recommended defaults and the post’s campaign Spring Sale!, a link https://example.com/news#top going to a channel called Company Page on LinkedIn goes out as:
https://example.com/news?utm_source=linkedin&utm_medium=social&utm_campaign=spring-sale&utm_content=company-page#topHost matching is exact: only the listed host is tagged (a leading www. is ignored on both sides, and an internationalised host matches by its punycode form). Subdomains need listing: example.com doesn’t tag shop.example.com, and shop.example.org doesn’t tag example.com. A port in the link doesn’t matter. Tagging a link that is already tagged changes nothing.
A link to one of your pages is always your own. A page picked with Umbraco’s link picker, or the page a post is about, is tagged whatever host its address is on, unless that domain is switched off. In the composer’s previews and checks, a page that isn’t live yet is shown by a stand-in address, and that is tagged too, so the preview has the length the post will have when it goes out.
Locks and a post’s own values
Section titled “Locks and a post’s own values”| Field is | What a post can do | What goes out |
|---|---|---|
| Locked | Nothing: the field is disabled, and a saved value for it is refused (utm.field_locked:<field>). |
Always the central value. |
| Unlocked | Set its own value. | The post’s value, or the central default when it has none. |
The values a post sets for itself (the source, medium and content, each at most 100 characters, and the opt-out) are removed when the post is deleted, and when it is sealed by the free edition’s history window: they matter only until the post goes out, and the tagged links are already live.
The API
Section titled “The API”All of these need UmbSocial Pro to be licensed (licence.pro_required otherwise).
| Request | Needs | What it does |
|---|---|---|
GET and PUT /umbraco/management/api/v1/umbsocial/pro/settings/links |
ManageSettings | The link settings: utmEnabled, utmDomains, utmSource, utmMedium, utmCampaign and utmContent (each { "default": "…", "locked": true }) and utmSourceByNetwork. |
GET and PUT /umbraco/management/api/v1/umbsocial/pro/posts/{key}/utm |
Write, and the post must be one the person may change | A post’s own source, medium, content and disabled. Saving all empty removes them. A locked field is refused (utm.field_locked:<field>). Who may change the post is the core’s own rule (post.not_yours), and a sealed post or one being sent can’t be changed (post.sealed, post.in_flight); those can still be read. |
GET /umbraco/management/api/v1/umbsocial/pro/utm/fields |
Write | Which fields are locked and their defaults, so a writer sees them without Settings access. |
POST /umbraco/management/api/v1/umbsocial/pro/utm/preview |
Write | Each channel’s link as it will go out, from the values being edited. Nothing is saved. A key that isn’t a channel is left out of the answer. |
From code, the same work is done by ILinkSettingsService, IPostUtmService and IUtmService (UmbSocial.Pro.Links). Pro’s services check the licence themselves, not only its endpoints: while UmbSocial isn’t licensed, a service that changes something refuses with licence.pro_required and changes nothing, and one that reads finds nothing. IUtmService then leaves a link as it is, with the reason off; reading the settings still works.
The settings are kept in Umbraco’s key/value store under UmbSocial.Pro.Links., and saving writes only the keys that changed. They are read through Umbraco’s runtime cache until they are saved, and saving clears them on every server of the site through Umbraco’s cache refresher. A change made directly in the database shows only after a save or a restart. A post’s own values are rows in Pro’s own table, umbSocialProPostUtm (a table of Pro’s own, as the key/value store is for a handful of site-wide values).
Notifications
Section titled “Notifications”In UmbSocial.Pro.Notifications. The “…ing” ones run before the change: cancel one with an error message to refuse it (link_settings.cancelled:<message> or utm.cancelled:<message>).
| Notification | When | Properties |
|---|---|---|
SocialLinkSettingsSavingNotification |
Before the link settings are saved. Change Target.Settings, or cancel. |
Target (SocialLinkSettingsDraft: Settings), Existing. |
SocialLinkSettingsSavedNotification |
After they were saved. | Settings. |
SocialPostUtmSavingNotification |
Before a post’s own values are saved. Change Target.Values, or cancel. |
PostKey, Target (SocialPostUtmDraft: Values), Existing. |
SocialPostUtmSavedNotification |
After they were saved (all empty when they were cleared). | PostKey, Values. |
Tagging and shortening are two steps of UmbSocial’s link rewriters (see Replacing services): UtmLinkRewriter, then ShortLinkRewriter, both in UmbSocial.Pro.Links. A step of your own can go between them with builder.OutgoingLinkRewriters().InsertBefore<ShortLinkRewriter, MyStep>(), so a short link keeps what your step added. Register your own IOutgoingLinkRewriter and it replaces the whole pipeline, Pro’s steps included: Pro then logs a line at startup saying its tagging and short links aren’t in use, and it warns if its steps are missing or out of order.
With the Umbraco Engage add-on, a third step goes between them: it adds the post’s marker, us=<code>, to links to your own site, just before they are shortened. In Engage’s own reports, the source and medium show as one column (linkedin / social); to see each channel there, set the medium default to social-{channel}.
To know a link again when it is sent a second time (to reuse its short link, or to match a link you chose to shorten), Pro compares it without its utm_ parameters and without a us parameter. That is the marker the Engage add-on adds. So if your own links use a us parameter, two links that differ only in its value count as the same link there.