Some features
Here you’ll find some extra Shlink features, which are not as evident, but you might still want to take advantage of.
This document also tries to clarify why some of these features work the way they do.
- Short URL title
- Query params forwarding
- Extra path forwarding
- Multi-segment custom slugs
- Short URLs trailing slash
- Short URLs mode
- QR Codes
- Bot detection
- Remove expired links
- Email tracking
- Service healthiness
- Device-specific redirects
Short URL title
Shlink v2.6.0 introduces the ability to optionally set a title
for every short URL.
The title can be provided, but it’s also possible to enable title auto-resolution. When that’s enabled, and the title is not provided, Shlink will try to infer the title by calling the long URL and picking the value inside the <title />
tag.
The title can be changed later on. If the long URL is changed, it will also try to auto-resolve the new title, unless the title was originally provided during creation.
Query params forwarding
By default, Shlink automatically forwards to the long URL all query params originally sent to the short URL.
For example, if you have a https://exam.ple/abc123
URL that points to https://www.google.com
, when users visit https://exam.ple/abc123?foo=bar
, they will get redirected to https://www.google.com?foo=bar
.
If for any reason the long URL already had query params, they will be merged with the ones sent to the short URL. In case of conflict, the value sent with the short URL will take precedence over the original URL one.
For example, if https://exam.ple/abc123
points to https://www.google.com?foo=bar
, when users visit https://exam.ple/abc123?foo=overwritten&another=param
, they will get redirected to https://www.google.com?foo=overwritten&another=param
.
Note
Starting with Shlink v2.9.0, this behavior can be overwritten on every individual short URL, allowing to disable the query params forwarding if desired.
Extra path forwarding
Starting with Shlink 2.8.0, Shlink can match short URLs as soon as the visited URL starts with an existing short code.
When this happens, Shlink will append the rest of the path to the long URL before redirection.
For example, if you have a https://exam.ple/abc123
URL that points to https://www.twitter.com
, you can make Shlink capture visits to https://exam.ple/abc123/shlinkio
and redirect to https://www.twitter.com/shlinkio
.
When this happens, Shlink will track the visit as usual.
This behavior needs to be actively opted in, as it’s disabled by default.
Multi-segment custom slugs
Shlink 3.2.0 introduced the ability to create short URLs with multi-segment custom slugs.
That means that you can provide multiple parts separated by slashes as the custom slug, ending with something like https://exam.ple/my/custom/campaign
.
This feature has some considerations though:
- When this is enabled, any URL will match a potential short URL. That means any future orphan visit will have either
base_url
orinvalid_short_url
types, but neverregular_404
. - Because of previous point, this is considered a breaking change, and therefore, it’s disabled by default, and you have to actively opt in.
- If Extra path forwarding is also enabled, there’s always a chance of conflict. If you have both
https://exam.ple/foo
andhttps://exam.ple/foo/bar
, when the second one is visited, it will match the first one, and the/bar
part will be forwarded to the long URL.
Short URLs trailing slash
Starting with Shlink 3.3.0, you can make the same short URL work whether it has a trailing slash or not. (This feature has to be explicitly enabled via installation tool or environment variables).
This means that, while the feature is enabled, if you create the short URL https://examp.le/foo
and a user ends up visiting https://examp.le/foo/
, the visit will be properly captured and the user will be redirected.
In older versions of Shlink or when this is not enabled, visiting a short URL with trailing slash results in a 404.
If you want to support trailing slashes in any route known by Shlink and not only short URLs, you can configure the web server in front of Shlink to strip trailing slashes before calling it:
- Nginx: https://ubiq.co/tech-blog/remove-trailing-slash-in-nginx/
- Apache: https://ubiq.co/tech-blog/how-to-remove-trailing-slash-in-apache/
- Caddy: https://caddy.community/t/efficient-remove-trailing-slash-redirect/3289
Short URLs mode
By default, Shlink always matches short URLs in a strict
mode, meaning it does a case-sensitive check when trying to determine which short URL has been visited.
This effectively means https://s.test/aaabbb
and https://s.test/AAABBB
are considered different URLs by Shlink.
Starting with Shlink v3.5.0, you can customize this behavior, and make Shlink consider those two URLs to be the same.
This is achieved via the so called loose
short URL mode (the mode can be set via installation tool or environment variables).
Warning
Setting loose
mode has a couple of considerations:
- Shlink will no longer generate short codes with uppercase letters. Only lowercase and numbers will be taken into consideration.
- When providing a custom slug, Shlink will lowercase it, so if there’s a URL with
aaabbb
andAaaBbb
is provided, it will throw an error saying it already exists. - On existing Shlink instances, already existing short URLs will not be changed in any way. If “conflicting” URLs already exist, they have to be fixed manually.
- Loose checks are done only for “public” URLs (short URLs, QR codes and email tracking). REST API endpoints do strict matches no matter what.
QR codes
Shlink comes with built-in support to generate QR codes for any short URL.
Getting a QR code URL is as simple as appending /qr-code
to any short URL. So if your short URL is https://exam.ple/abc123
, the URL which returns the binary QR code image is https://exam.ple/abc123/qr-code
.
The image’s default appearance can be customized via installation tool or env vars, but it can also be customized on the fly via query params:
size
: It determines the width/height in pixels. Default value is 300 and accepts values from 50 to 1000.margin
(since v2.6.0) : The space in pixels between the QR code itself and the border of the image. Default value is 0 and accepts positive numbers.format
(since v2.4.0) : Can bepng
orsvg
. Default values ispng
.errorCorrection
(since v2.8.0) : Can beL
(Low),M
(Medium),Q
(Quartile) orH
(High). Default value isL
. Learn more.roundBlockSize
(since v2.10.0) : Can betrue
orfalse
. Tells if the block size should be rounded, making the QR code more readable, but potentially adding some extra margin as a side effect.color
(since v4.0.0) : Foreground color in hexadecimal, with 3 or 6 characters. Default value isblack
if not provided or provided value is not a color.bgColor
(since v4.0.0) : Background color in hexadecimal, with 3 or 6 characters. Default value iswhite
if not provided or provided value is not a color.
For example https://exam.ple/abc123/qr-code?size=500&format=svg&margin=20&errorCorrection=Q&roundBlockSize=false
.
See the “endpoint” docs for more information.
Considerations
- The total size of the image will be determined by the size + the margin times two. So, if the size is 500 and the margin is 20, the resulting image will be 540x540 pixels.
- The logo cannot be customized via query params, to avoid public QR codes from being unintentionally associated with certain images.
Bot detection
Starting with v2.7.0, Shlink can now detect visits from potential bots or crawlers, based on the visitor’s User-Agent
header.
Of course, there’s never a 100% accuracy here, hence the potential.
All the endpoints serving visits will include the potentialBot
flag with values true
or false
, and they also allow excluding potential bots from the result set.
Remove expired links
Sometimes you programmatically create “temporary” links that are meant to be used once or during a short period of time, and then get disabled via maxVisits
or validUntil
.
After some time, you can end up with a bunch of short URLs consuming space, that are never going to receive new visits.
While Shlink does not provide a mechanism to automatically delete them once expired, starting with Shlink 4.1.0, you can use the short-url:delete-expired
command to delete all links that are considered expired by the conditions mentioned above.
It’s up to you to configure this command to be run periodically if desired.
Email tracking
Shlink can track how many times an email has been opened, by taking advantage of its URL tracking capabilities.
You can track emails with any existing short URL, or create a new one pointing to a dummy long URL (the redirect itself is not important for this use case).
Then, by appending /track
to the short URL, you will have a new URL (for example, https://example.com/abc123/track
) that resolves to a 1px transparent image. Add it to any email you want to track.
The image is effectively invisible, but every time the email is opened and the image is loaded, Shlink will count one visit.
Service healthiness
In some situations you may want to know if your Shlink instance is healthy. Reasons might include monitoring, but also letting orchestrators know if one specific instance can respond to requests.
Shlink exposes a /rest/health
endpoint, which does not require authentication, and can be used for this purpose.
You can find more information in the API docs.
Device-specific redirects
Shlink 3.5.0 introduced the possibility to dynamically redirect to different long URLs depending on the device used by the visitor.
Shlink v4.0.0 has moved this into a new dynamic rule-based redirects system.