Custom Tealium Event Tracking in Drupal – Behind the Code

Tealium is a powerful tag management solution used by enterprises to streamline and scale their digital analytics. When it comes to integrating it with Drupal, especially for custom event tracking, things can get a bit tricky — particularly if you’re aiming for a dynamic, flexible, and production-ready solution.

In this article, we’ll walk through a real-world implementation of custom Tealium event tracking in Drupal, breaking down the code, the configuration, and the logic behind a scalable approach.

🧩 The Requirement

We had a client using Tealium to track user interactions like:

Clicks on CTAs (“Download Now”, “Contact Us”, etc.)
Outbound links
PDF or document downloads

But they needed the following:

Custom tracking events for different user actions
A solution flexible enough to add/edit events without code changes
Environment control – only fire in production
A Drupal-native solution that could scale with their content

🔧 The Solution: A Modular Drupal Setup

We built a custom Drupal module, architected into two parts:

1. `tealium_event` (Core Logic)

This contains the reusable logic, JavaScript injection, and base config handling.

2. `gson_tealium_event` (Project-Specific Layer)

This holds YAML files with tracking definitions, config forms, and project-specific event settings.

This modular approach made our solution:

Reusable across Drupal projects
Maintainable (clear separation of logic and configuration)
Easy to extend for future tracking needs

📁 YAML Configuration: The Heart of It

We used YAML files to define all event rules, like this:

cta_contact:
  url_pattern: "/contact"
  link_text_contains: "Contact Us"
  event_data:
    event_name: "contact_us_click"
    category: "CTA"
    label: "Contact Us Button"

This allowed the marketing or QA teams to:

Add or modify event rules
Skip developer involvement for every change
Maintain a clean and readable format

💻 The JavaScript: Listening & Triggering Events

Once the YAML config was loaded in PHP, we passed it to the frontend via drupalSettings.
Our JavaScript then:

Scanned the page for <a> tags
Checked each link’s href and textContent for a match
Triggered utag.link() with the configured event data

javascriptCopyEditdocument.querySelectorAll('a').forEach(link => {
  link.addEventListener('click', () => {
    if (link.textContent.includes("Download Now")) {
      utag.link({
        event_name: "download_cta_click",
        category: "CTA",
        label: "Download Resource"
      });
    }
  });
});

Eventually, we looped through the full list of YAML-defined rules dynamically to fire the right event based on matches.

🧪 Admin UI: Built for Control

To make the solution even more robust, we created a Drupal config form:

Enable/disable Tealium tracking
Restrict firing to production environment only
Provide a live preview of YAML-defined event rules

This gave site admins full visibility and control — and avoided surprises in staging or dev.

🔒 Production-Only Tracking

To ensure tracking only runs in production, we added an environment variable toggle:

$config['tealium_event.settings']['enabled'] = getenv('TEALIUM_ENABLED') ?: FALSE;

Now, even if the module is installed everywhere, Tealium events won’t fire unless explicitly enabled.

✅ Benefits of This Approach

This setup delivered several wins:

Benefit	Description
🔄 No redeployments	Marketing can manage event logic via YAML
⚙️ Dynamic & Scalable	Add more events without writing more JS
🧠 Separation of Concerns	Developers handle structure, marketers handle rules
🔐 Production-Only Logic	Clean, test-safe architecture
🧰 Reusable Module	Can be ported across Drupal projects easily

📈 Final Thoughts

If you’re using Drupal and need custom, dynamic event tracking with Tealium, this method offers a clean, scalable, and professional solution.

It blends:

The power of Drupal’s configuration system
The flexibility of YAML
The speed of JavaScript
And the control required for enterprise-grade data accuracy

💬 Want Help Implementing It?

If you’re building something similar, or want to integrate Tealium tracking in your Drupal site — feel free to reach out. I’d be happy to collaborate, share code, or assist with implementation.

Let’s make smarter data-driven sites, the Drupal way.

🔖 Tags:

#Drupal #Tealium #WebAnalytics #Drupal10 #OpenSource #JavaScript #TagManagement #WebDevelopment #DrupalModules