Shortlink Manager: A Hitchhiker's Guide to Better Analytics

Every Drupal developer who runs a content site eventually faces the same problem: you write a post with a clean, SEO-friendly URL, and then you need to share it. Suddenly you're staring at something like https://example.com/blog/category/your-extremely-descriptive-post-title… and thinking there has to be a better way.

There is. But not from a third-party service that takes your data off-platform, locks you into their branding, and gives you no native integration with your Drupal content. I built the Shortlink Manager module because I needed something native — a solution with complete control over the data, the branding, and the workflow.

This series documents that build: every architectural decision, every feature addition, and every lesson learned along the way. If you're a Drupal developer who manages marketing campaigns, content distribution, or multi-channel tracking, this is the complete reference.

The module is open source: https://github.com/r0nn1ef/shortlink_manager

What the Shortlink Manager Does

At its core, the module turns a long URL into a short, trackable redirect path — /go/alsu9-m77t instead of the full campaign URL. But the architecture goes significantly further than that.

The key capabilities:

• Custom content entity for shortlinks with full Drupal field support
• UTM Sets — reusable campaign parameter templates that auto-apply to any shortlink
• Auto-generation of shortlinks when content is published
• Click analytics — per-click tracking with referrer, user agent, and timestamp data
• Intelligent expiration — links that retire themselves by date, click count, or inactivity
• QR code generation — downloadable PNG codes for offline-to-online campaigns
• Shortlink Block — a display widget that surfaces the shortlink for the current page
• Drush commands — full CLI management for power users and automation
• Feeds importer — bulk import shortlinks from CSV

The Architecture

The module is built around a non-fieldable content entity — Shortlink — that represents a single tracked redirect. This entity holds:

• path — the unique slug (e.g., alsu9-m77t)
• utm_set — an entity reference to a reusable UTM Set configuration
• target_entity_type and target_entity_id — allowing a shortlink to point at any Drupal entity, automatically resolving its canonical URL
• destination_override — for external URLs or internal paths that aren't entities

The entity's resolveDestinationUrl() method handles the redirect logic: check for an override first, fall back to the entity's canonical URL if not. Campaign parameters are assembled from the associated UTM Set and appended automatically at redirect time.

Why a content entity and not config? Because shortlinks are data, not configuration. They need revision history, access control, and views integration — things you get for free with a content entity.

UTM Sets: Eliminating the Spreadsheet

The UTM Sets feature was the original forcing function for building this module. Before it existed, generating a tracked link meant opening a spreadsheet, manually combining the destination URL with utm_source, utm_medium, utm_campaign, utm_content, and utm_term for every social channel — every time. UTM Sets also allow you to add custom parameters for any custom metrics for your site!