Knowledge Base

Everything about TrueSlug: step-by-step setup, every feature explained honestly, and fixes for the things that go wrong.

Getting started

Install & activate

Requirements: WordPress 6.0+, PHP 7.4+. No external accounts needed.

In wp-admin go to Plugins → Add New → Upload Plugin and upload the trueslug.zip file (or copy the trueslug folder into wp-content/plugins/).
Click Activate. The setup wizard opens automatically.
Follow the six steps: welcome, first link, essentials, recommended features, Pro trial, done.

The setup wizard

The wizard runs once after activation and can be reopened any time at admin.php?page=tslug-wizard. Every step saves something real and every step can be skipped. You can always come back later from the TrueSlug menu.

Create your first link

TrueSlug → Add New
Name — an internal label, e.g. "Amazon — Kitchen Deals".
Destination URL — the long, ugly target, including https://.
Slug — leave empty to auto-generate from the name, or click Generate for a random short code.
Click Create Link. Your short link is yoursite.com/go/slug — use the Copy button.

Tip: pick slugs a human would trust, like /go/nike-deal — clean slugs get more clicks than random codes.

Use links in posts

Block editor: select any text → click the chain icon → paste your short link. Or simply type the short link on its own line — WordPress links it automatically.
Classic editor: select text → the link button → paste the short link.
Widgets, menus, emails, social bios: short links work anywhere a URL works.

Read your numbers

TrueSlug → Dashboard shows human clicks, bots filtered, broken links and recent activity. Reports adds the 30-day chart, devices, referrers and per-link filtering. Every click is recorded as human or bot — you always see both numbers.

Features

Redirect types & cloaking

Type	Use it when
302 (default)	Almost always. Every click is tracked, you can change the destination any time, and search engines know not to index the short link.
301	Permanent moves only. Browsers may cache it and skip your tracking — that is what "permanent" means.

Every link can carry rel="nofollow" and rel="sponsored" — the attributes Google's guidelines ask affiliates to use.

Bot filtering

Every click is checked against known bots, crawlers, social link previews, uptime monitors and command-line clients. Results are recorded per click — human and bot counts are always shown side by side, and bots never pollute your human numbers. Honest scope: TrueSlug filters known bots and crawlers; no tool can identify every disguised bot, and we don't claim to.

Broken-link monitor

Once a day (or on demand from Reports → Check now), TrueSlug requests every link's destination in small batches. A destination is only marked broken after a HEAD check and a GET verification — so HEAD-unfriendly servers can't cause false alarms. If a link dies you get an email the same day; if it comes back, you get that email too. Configure the notification address in Settings.

Deliverability tip: WordPress sends mail through your host by default. Install any SMTP plugin (or Brevo SMTP) so alert emails land in your inbox, not spam.

Geo targeting

Add per-country destinations on any link: US → amazon.com, GB → amazon.co.uk. TrueSlug reads the visitor's country from the Cloudflare CF-IPCountry header — automatic and free on any Cloudflare-fronted site. No header means the visitor gets the main destination. No external API calls, ever.

Keyword auto-linking

Under TrueSlug → Keyword Links, map a keyword to a short link. TrueSlug then links the first occurrence of that keyword in your posts automatically — never inside existing links, capped per page (default 3, changeable in Settings). External links added this way go through your short link, so they're fully tracked.

Auto-cloak

With auto-cloak on, every external link in your posts is rewritten through a short link — reusing an existing link with the same destination, or creating one automatically. Your own domain and the skip list (e.g. wikipedia.org — subdomains included) are never touched. UTM-tagged links keep their manual tags.

UTM builder

Set source, medium, campaign, term and content on a link; they're appended on every redirect — unless the destination already has UTM tags (manual wins). Example: source instagram + campaign black-friday turns the destination into …?utm_source=instagram&utm_campaign=black-friday.

QR codes

Every short link has a QR code: the row action QR in All Links, or the inline code on the edit screen. Generated locally — no external service, nothing leaves your server.

Splash & coupon pages

Splash page: a branded card shown before forwarding — heading, message, button label, optional auto-forward delay. Use it for disclosures or a short intro. Coupon page: shows the discount code big and bold with a Copy button, then continues to the store — the classic coupon-site flow. Both are noindex and fire your pixels.

Link in Bio

Your own hosted bio page at yoursite.com/bio/ — avatar, name, bio text, your accent color, and a list of links. External links you add are automatically routed through TrueSlug short links, so bio clicks land in the same reports as everything else. Self-hosted: no third-party bio service, no extra domain.

Scheduling & click caps

Schedule: a link 404s before its start time and shows "expired" (HTTP 410) after its end time — built for Black Friday campaigns. Click cap: the link stops redirecting after N clicks. Times use your WordPress timezone.

Pixel tracking

A redirect can't fire pixels — browsers leave too fast. With pixel tracking on, short-link clicks serve a fast noindex page that fires your Google Analytics 4, Meta and/or X pixel, then forwards the visitor automatically (with a no-JS fallback). Add your pixel IDs in Settings.

Forward parameters

On any link, "Forward query parameters" passes the visitor's query string through to the destination — useful for sub_id, gclid and merchant tracking parameters.

Troubleshooting

Every short link gives 404

Go to Settings → Permalinks and click Save Changes — this rebuilds WordPress' rewrite rules. TrueSlug flushes them automatically on activation, but other plugins sometimes interfere.

Links stopped working after I changed the prefix

Changing the prefix updates every link at once and flushes rewrites automatically. If pages on your site use a path that clashes with your new prefix, pick another one — reserved WordPress paths (wp-admin, wp-json, feed…) are blocked by the plugin.

Clicks aren't counted

Check three things: (1) Settings → "Don't count my own visits" — as a logged-in admin your clicks may be ignored by design; (2) full-page caching — exclude your link prefix from page cache; (3) a 301 redirect you set earlier — browsers cache those and skip your server.

Geo targeting doesn't work on my test site

Geo targeting reads the Cloudflare country header, which only exists on Cloudflare-fronted sites. On localhost or non-Cloudflare hosting every visitor gets the main destination — that's the correct fallback.

Alert emails don't arrive

WordPress sends mail through your hosting by default, and many hosts don't configure it properly. Install an SMTP plugin (Brevo SMTP, WP Mail SMTP) or check your spam folder. On LocalWP, emails appear in Local's built-in Mail Catcher.

A destination shows as broken but works in my browser

Some servers reject the lightweight HEAD check. TrueSlug already verifies with a full GET before declaring a link dead, but if a server still blocks automated checks, whitelist that domain from monitoring by contacting support — or just ignore the badge; it never affects redirects.

Migrating from other plugins

In your old plugin, export links to CSV.
Open TrueSlug → All Links → Import (Pro) or match the CSV columns to ours: slug, name, destination, redirect type.
Keep your old plugin installed (deactivated) for a while and add redirects from its old URLs to your new TrueSlug links if any external site linked directly to the old paths.

One-click importers for Pretty Links and ThirstyAffiliates are on the roadmap.

Support

support@trueslug.com — include your WordPress version, PHP version and what you expected vs. what happened. Pro customers: use the same address with your license email for priority handling. Billing: billing@trueslug.com.