How to Automate UTM Parameters with a Drupal Module

What are UTMs, and Why Should You Care?

First things first: what exactly is a UTM parameter? In simple terms, it's a little snippet of text added to the end of a URL. Think of it as a digital fingerprint for your link. These parameters tell Google Analytics and other tracking platforms specific details about who clicked your link and how they found it. For a deeper dive into UTM parameters, I highly recommend visiting Analytics Mainia (https://www.analyticsmania.com/post/utm-parameters-in-google-analytics-4/).

There are five main types of UTM parameters:

• utm_source: The source of your traffic (e.g., facebook, newsletter).
• utm_medium: The marketing medium (e.g., social, email).
• utm_campaign: The specific campaign (e.g., fall_promo, new_product_launch).
• utm_term: Keywords for a paid ad.
• utm_content: Used to differentiate similar content or ads.

The result is a URL that looks a little more verbose, but provides a wealth of information:

https://example.com/go/sui49_nm?utm_source=facebook&utm_medium=social&utm_campaign=fall_promo

The Why: From Tedious to Terrific

So, why go through the trouble? Because understanding your traffic is the difference between guessing and knowing. UTMs help you:

• Measure ROI: Pinpoint exactly which campaigns, platforms, and ads are bringing in the most valuable traffic.
• Optimize Content: Understand which of your social media posts or email subject lines are performing best.
• Make Smarter Decisions: Allocate your resources to the marketing efforts that are actually working.

Before my module, for me, this meant opening a spreadsheet every single time I needed a new link – a manual, error-prone process. I knew there had to be a better way.

The Implementation: Introducing the UtmSet

My solution was to build the Utm Set as a reusable configuration entity within Drupal. This technical decision was a game-changer. In Drupal, content entities are for day-to-day, user-generated information, like a blog post, an e-commerce product, or a user profile. In contrast, configuration entities are for site-wide settings and reusable structures, like a content type or, in my case, a UTM Set. This distinction is what allows me to create and reuse tracking templates across all my content.

For the developers in the audience, this is what the entity annotation looks like which is how I told Drupal to store and export the individual UTM parameters:

/**
 * Defines the UTM Set config entity.
 *
 * @ConfigEntityType(
 *   id = "utm_set",
 *   label = @Translation("UTM Set"),
 *   label_collection = @Translation("UTM Sets"),
 *   label_singular = @Translation("utm set"),
 *   label_plural = @Translation("utm sets"),
 *   label_count = @PluralTranslation(
 *     singular = "@count UTM set",
 *     plural = "@count UTM sets",
 *   ),
 *   handlers = {
 *     "list_builder" = "Drupal\shortlink_manager\UtmSetListBuilder",
 *     "form" = {
 *       "add" = "Drupal\shortlink_manager\Form\UtmSetForm",
 *       "edit" = "Drupal\shortlink_manager\Form\UtmSetForm",
 *       "delete" = "Drupal\Core\Entity\EntityDeleteForm",
 *     },
 *   },
 *   config_prefix = "utm_set",
 *   admin_permission = "administer utm_set",
 *   links = {
 *     "collection" = "/admin/structure/utm-set",
 *     "add-form" = "/admin/structure/utm-set/add",
 *     "edit-form" = "/admin/structure/utm-set/{utm_set}",
 *     "delete-form" = "/admin/structure/utm-set/{utm_set}/delete",
 *   },
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label",
 *     "uuid" = "uuid",
 *   },
 *   config_export = {
 *     "id",
 *     "label",
 *     "description",
 *     "utm_source",
 *     "utm_medium",
 *     "utm_campaign",
 *     "utm_term",
 *     "utm_content",
 *     "status",
 *   },
 * )
 */

Instead of manually typing out utm_source=facebook and utm_medium=social for every single link that I post on Facebook or other social media platforms, I can now create a UtmSet once and reuse it across multiple shortlinks.

For example, you could create a UtmSet named "Facebook Promo" with utm_source set to facebook, utm_medium to social, and utm_campaign to fall_promo. Then, you can simply apply this set to any new shortlink you create for that specific campaign.

This approach not only saves an incredible amount of time but also ensures consistency across your data. No more typos in your UTM parameters!

The User Experience: Simple and Powerful

From a user's perspective, the process is incredibly simple. You navigate to the UtmSet configuration area, create a new set with your desired parameters, and save it. When you create a new shortlink, a simple dropdown menu allows you to select and apply any of your pre-configured UTM Sets. Just like that, your shortlink is not only clean and simple, but also packed with valuable tracking information.