Short links
With UmbSocial Pro licensed, the links in your posts can be shortened by your own site: no account with a link-shortening service, and no one else sees your clicks. Each channel gets its own short link for the same address, so you can see which channel brought the visitors.
The post as you wrote it is never changed. The link is shortened as the post goes out to each channel, after the UTM tags are added (see UTM Tags), and the composer’s previews and character counts show a short link of the length it will have.
Which links are shortened
Section titled “Which links are shortened”Every link in a post that points to one of your site’s own domains is shortened. That covers the post’s text, each part of a thread and the first comment. A link to anywhere else is left exactly as you wrote it: it is not shortened, and no short link is made for it.
Your site’s own domains are:
- the domains set up in Umbraco (Content › Culture and Hostnames), except any you switch off under Settings › UmbSocial › Links;
- the host of the main URL, if you set
Umbraco:CMS:WebRouting:UmbracoApplicationUrlexplicitly; - the host of the Short link address, if you set one.
A host is compared by its name alone: capital letters, a trailing dot (example.com.) and the international form of a name (bücher.example or xn--bcher-kva.example) make no difference, and a leading www. is ignored. A subdomain counts only when Umbraco has it as a domain, so blog.example.com is not shortened unless it is one of your domains. A link that already is one of your short links is left as it is.
A domain you add in Umbraco later is included at once, without saving any settings.
Shorten one external link
Section titled “Shorten one external link”Sometimes you want a link to another site shortened too. In the composer, highlight the link in the text and select Shorten link in the toolbar. The link is then listed under the button as Will be shortened, and it is shortened on this post, on every channel. To take it back, highlight it again and select Don’t shorten.
The button works only when what is highlighted is exactly one https link. It is off for a link to your own site (already shortened: the button says so), for anything else that is highlighted, and for a post you can’t change.
The links you choose are part of the post. Choosing one counts as a change to the post, so leaving without saving asks whether to discard it, and Discard puts the saved list back. They are saved when you save the post, by hand or by autosave, and they are cleared once the post’s history is sealed or the post is deleted. The composer’s previews show a short link for a chosen link as soon as the post has been saved: the composer checks the post again after that save. A switched-off domain is left as written even when a link to one of its pages is picked with Umbraco’s link picker.
Switch it on
Section titled “Switch it on”Short links are off on a new site. Switch them on in Settings › UmbSocial › Links (needs ManageSettings), in the Short links box:
- Shorten outgoing links turns shortening on. Off, links go out in full. Short links already made keep redirecting.
- Short link address is an
httpsaddress with nothing after the host name, such ashttps://go.example.com. Leave it empty to use this site’s first domain (or the main URL if you setUmbraco:CMS:WebRouting:UmbracoApplicationUrl; Umbraco’s own guess of its main URL, taken from the first request, is never trusted). With neither, set the address. - Path is the one word the codes live under. It is
/s/by default, so a link looks likehttps://go.example.com/s/Ab3dE5g.umbraco,api,mediaandApp_Pluginscan’t be used, and neither can a word a published page of your site already starts its address with.
Switching short links on with no address to use (no short link address, no domain on the site and no UmbracoApplicationUrl) is refused with a message saying so; if the address goes away later, links go out in full and one warning is logged.
Changing the address or the path breaks the links already posted, because the old address is the one written in those posts. Choose them once. The address must be https; if it somehow isn’t, links go out in full rather than over http. Settings are cached on each server until they are saved, and saving clears them on every server of the site at once, through Umbraco’s cache refresher.
A separate short domain
Section titled “A separate short domain”A short domain such as go.example.com looks better in a post than a long one. It is the same site answering on another name:
- Add the domain as a binding for your site in your hosting (a host header in IIS, an extra host name in your reverse proxy or container platform) and point its DNS at the site.
- Make sure it has a certificate, because short links must be
https. - Put it in Short link address.
Nothing else is needed: the site answers a short link on whatever name it is reached by.
What a short link does
Section titled “What a short link does”A short link goes to the address it was made for, with a plain redirect. Short links are served by Umbraco’s own routing (the way Umbraco’s own redirects are), so a real page at the same path always wins, and a separate short domain bound in Culture and Hostnames works like any other. Only a link UmbSocial made redirects: nothing in the web address you type, such as ?url=, ever chooses where a visitor is sent, so the redirect can’t be used to send people to another site. A code that does not exist, a link you removed, a link to a page that is no longer published, and anything under the path that isn’t a code are all left to Umbraco, which answers your site’s normal 404: nothing in the answer tells them apart. A client that asks for more than 120 short links a minute gets a 429 Too Many Requests from ASP.NET Core’s rate limiter before Umbraco routes the request, and nothing is counted. Only requests under the short link path are limited, an IPv6 client by its /64, and the limit is kept in memory, never stored. It is added to any global rate limiter your site sets (however late) and leaves the status and handler you configured for your own limits alone.
Behind a reverse proxy or load balancer, set up forwarded headers, or every visitor has the proxy’s address and shares one limit. In Program.cs, before Umbraco:
builder.Services.Configure<ForwardedHeadersOptions>(options =>{ options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto; options.KnownProxies.Add(IPAddress.Parse("10.0.0.2")); // or KnownNetworks.Add(...)});
app.UseForwardedHeaders();app.UseUmbraco()...If a request from a private address arrives with an X-Forwarded-For header that was not applied (no X-Original-For, or the header name set in ForwardedHeadersOptions.OriginalForHeaderName), a warning is logged once. It is a hint, not a check: a client can forge the original-for header, and a proxy that sends CF-Connecting-IP or X-Real-IP instead is not noticed.
The redirect is 302, not 301. Browsers keep a 301 for good, which would stop a link you later edit from changing, and would hide repeat visits from the count. The answer is also marked so browsers don’t keep it.
A link to a page of your own site is remembered as that page (by its key, the way Umbraco’s link picker does), so the short link follows the page when it is renamed or moved. A link to anywhere else is remembered as its address.
What is counted
Section titled “What is counted”Every time someone opens a short link (a GET), its count goes up by one. That includes the people who preview links, such as a chat app fetching a page’s title, because from the server they look like visitors. A HEAD request, which monitors and some crawlers send, is answered but not counted.
The count is a number and nothing else. Nothing about the visitor is kept: no IP address, no browser, no cookie, no referrer. That makes short link counts free of personal data, and it also means a visitor can’t be counted once only: the same person opening a link twice is two clicks.
Where you see the counts:
- The queue and the calendar show a tag such as Link clicks (UmbSocial): 12 on posts that have short links, with each channel’s count when you hover over it. One request fetches the whole page. These are never added to the clicks a network counts itself: see Clicks: ours and the network’s.
- Published shows a post’s short links with the clicks of each.
- UmbSocial › Short links lists every short link.
With the Umbraco Engage add-on, Engage’s visits are shown beside the clicks: 12 link clicks (UmbSocial) · 5 visits (Engage). The two are different counts and are never added together: a visit counts only someone who allowed analytics and whose browser ran Engage’s script, once per visit.
Anyone who can read a post sees its clicks, as with its views and interactions: with View, every post’s; with Write alone, those of their own posts.
Manage short links
Section titled “Manage short links”The Short links page is in the UmbSocial section’s own sidebar, under UmbSocial › Short links, so you don’t need access to Umbraco’s Settings section to use it. You do need the Manage settings permission on your UmbSocial user group. The page lists every link, newest first, with its code, where it goes (a page by name, linked to it, or a web address), its post, its channel, its clicks and when it was made. Use the filter to search by code or address.
- Edit target changes where a link goes: pick a page of your site, or a web address, in Umbraco’s link picker, then confirm. Everywhere the link was posted will now go to the new target. The code never changes and the clicks carry on. The new target is used as you choose it: add UTM tags to an external address yourself if you want them.
- Remove makes the link stop working wherever it was posted: visitors get your site’s 404. It can’t be undone, and the code is never used again.
Both actions are written to the post’s History (Short link target changed, Short link removed). The first time a post’s links are shortened, one Links shortened entry is written: clicks are not written to History, which would drown it.
When the licence lapses
Section titled “When the licence lapses”Short links already posted keep redirecting, and keep counting, so live posts never break and nothing is deleted. What stops is making new ones: posts that go out while UmbSocial isn’t licensed carry their full links, and the settings, the click counts and Edit target are Pro features and are unavailable until it is licensed again.
UmbSocial › Short links and Remove still work while UmbSocial isn’t licensed. A link keeps redirecting after the licence lapses, so if its target goes bad (a page you no longer want shared, or an external address that now serves something harmful), you can still find the link and take it down.
For developers
Section titled “For developers”The shortener is pluggable: register your own IShortLinkProvider and it is used instead of the site’s own. Pro’s own shortener and IShortLinkService check the licence themselves: while UmbSocial isn’t licensed, the shortener leaves every link as it is, a post’s links and the click counts are empty, and editing a link is refused with licence.pro_required. Following a link and counting its click, the management list (ListAsync) and removing a link (RemoveAsync) work whatever the licence. A retry of the same link for the same post and channel gets the same short link, even if the post’s UTM values or its campaign’s value changed in between. Handlers can take part through these notifications, in UmbSocial.Pro.Notifications:
| Notification | When |
|---|---|
SocialShortLinkCreatingNotification |
Before a link is made. Cancelable: the link then goes out in full. A handler can change the code or the target. |
SocialShortLinkCreatedNotification |
After a link is made. |
SocialShortLinkClickedNotification |
A link was followed (code, post and channel; no visitor data). Keep the handler quick. |
SocialShortLinkEditingNotification / SocialShortLinkEditedNotification |
Before and after a target changes (cancelable before; the old and the new target after). |
SocialShortLinkRemovingNotification / SocialShortLinkRemovedNotification |
Before and after a link is removed (cancelable before). |
The management API is under /umbraco/management/api/v1/umbsocial/pro/: GET short-links (paged, with a filter), PUT short-links/{code} (exactly one of contentKey or url) and DELETE short-links/{code}, all ManageSettings (the list and the delete also work while UmbSocial isn’t licensed); GET posts/{key}/short-links, with View; and POST short-links/clicks with { "postKeys": [ … ] } in the body (at most 200 posts, or short_links.too_many_keys), by the posts lists’ read rule: View, or Write for the caller’s own posts, and a post the caller can’t read is left out.
IShortLinkService.LinkClicksAsync(postKeys) returns each short link of up to 200 posts with its post, channel, code and clicks (ShortLinkClicks), in one query, for an add-on that shows its own figures per link. Removed links are left out; it returns null for more than 200 posts, and an empty list while UmbSocial isn’t licensed.
In the backoffice, the Short links list has an extension slot in each row’s clicks cell, umbSocialProShortLinkDetail. Each element gets the row’s link as item (its code, post and channel); to load data for every row at once, consume Umbraco’s UMB_COLLECTION_CONTEXT and read its items. Pro’s Link clicks (UmbSocial) detail on each post (an umbSocialQueueItemDetail) has weight 200, so a detail of yours weighted just below it, such as 199, is drawn right after it. The Engage add-on uses both.