Download the PHP package marshmallow/marketing-data-tracker without Composer

🎯 Laravel Marketing Data Tracker

Comprehensive Marketing Attribution & UTM Parameter Tracking for Laravel

Track, store, and analyze marketing attribution data from Google Ads, Facebook, TikTok, LinkedIn, and 10+ other advertising platforms in your Laravel application. Automatically capture UTM parameters, click IDs, and conversion data to understand your marketing performance and ROI.

Perfect for e-commerce sites, SaaS applications, and any Laravel project that needs comprehensive marketing attribution tracking.

✨ Features

🚀 Multi-Platform Support - Google Ads, Facebook/Meta, TikTok, LinkedIn, Twitter, Pinterest, Microsoft Ads, Reddit, Snapchat, and more

🎯 Intelligent Click ID Tracking - Automatically detect and prioritize gclid, fbclid, ttclid, msclkid, and other platform-specific identifiers

📊 UTM Parameter Management - Complete UTM tracking with automatic parameter extraction and storage

🔄 Conversion Attribution - Link conversions back to their original marketing source with full attribution data

🍪 Advanced Cookie Support - Track 60+ marketing cookies across all major advertising platforms

⚡ Zero Configuration - Works out of the box with sensible defaults, fully customizable

🛡️ Privacy Compliant - Built-in GDPR support with consent management and data export

📱 Mobile Attribution - iOS 14.5+ support with gbraid and wbraid tracking

🎨 Laravel Nova Integration - Beautiful admin interface for viewing marketing data

🚀 Quick Start

Installation

Install via Composer:

Publish and run migrations:

Basic Setup

1. Add the trait to your models:

2. Add the middleware to your web routes:

On Laravel 11+ register it in bootstrap/app.php:

On Laravel 10, add it to the web group in app/Http/Kernel.php:

3. Track marketing data on user registration:

That's it! 🎉 The package will now automatically track marketing parameters from all major advertising platforms.

📖 Platform Support

Enhanced Multi-Platform System

The package now features a comprehensive platform management system supporting 12+ advertising platforms with configurable parameters, cookies, and tracking templates.

Supported Advertising Platforms

Platform Configuration

Each platform can be individually enabled/disabled and configured:

Automatic Parameter Detection

The package automatically detects and stores 175+ marketing parameters:

• Standard UTM: utm_source, utm_medium, utm_campaign, utm_term, utm_content
• Google Ads: gclid, gbraid, wbraid, mm_campaignid, mm_adgroupid, mm_keyword, etc.
• Facebook: fbclid, campaignid, adsetid, adid, placement, site_source
• Email Marketing: mc_cid (Mailchimp), utm_email, list_id
• Affiliate Programs: ref, affiliate_id, partner_id

🎯 Usage Examples

Basic Marketing Attribution

Advanced Click ID Management

The package now features priority-based click ID detection with configurable extraction and cookie support:

Click ID Priority Configuration

E-commerce Conversion Tracking

Enhanced e-commerce tracking with Google Tag Manager format and multiple platform support:

E-commerce Configuration

Campaign Performance Analysis

⚙️ Configuration

Publish the configuration file:

Platform-Specific Configuration

Cookie Consent Management

Consent handling lives under the cookie_management key, which also groups cookies into analytics, advertising, and functional buckets:

When auto_register_exceptions is enabled (the default), the package automatically adds all configured marketing cookies to Laravel's EncryptCookies exceptions so they can be read in plain text.

🔧 Advanced Features

Marketing URL Builder

NEW: Fluent URL builder with platform-specific templates and ValueTrack parameter support:

URL Builder Features

• ✅ Platform Templates: Pre-configured URLs for Google Ads, Meta, Microsoft, LinkedIn, Twitter, TikTok, Pinterest
• ✅ ValueTrack Support: Full Google Ads ValueTrack parameter integration
• ✅ Dynamic Parameters: Meta/Facebook dynamic parameter placeholders
• ✅ Fluent Interface: Chainable methods for easy URL construction
• ✅ Parameter Filtering: Automatic filtering of empty/null values
• ✅ Template System: Use tracking URL templates from configuration

Event-Driven Architecture

NEW: Comprehensive event system for marketing data lifecycle tracking:

Event Configuration

Laravel Nova Integration

🎨 Platform-Specific Setup

Google Ads Configuration

Add to your Google Ads account-level tracking template:

Facebook Ads Configuration

Use Facebook's URL parameters in your ads:

Server-Side Tracking Setup

For accurate attribution, configure server-side tracking:

🏗️ Architecture

Database Schema

The package creates a flexible marketing data storage system:

Privacy & GDPR Compliance

• Consent Management: Built-in cookie consent handling
• Data Anonymization: Automatic PII detection and masking
• Data Export: GDPR-compliant data export functionality
• Retention Policies: Configurable data retention periods

📊 Analytics Integration

Google Analytics 4

Facebook Conversions API

Forward conversions to the Facebook Conversions API by listening for the ConversionTracked event and using the attribution data it carries:

Custom Analytics Platforms

🧪 Testing

Testing Marketing Attribution

🚀 Performance

• Minimal Database Impact: Marketing data is stored as JSON on a single related row per model.
• Lazy Loading: The marketing_data relation is loaded only when accessed.
• Path Filtering: Use the ignore_paths config to skip parsing on routes that never carry marketing parameters.
• Batch Writes: Use setMarketingDataBatch() on a model to write multiple parameters in one operation.

🛠️ New Advanced Features

Automatic Model Observation

NEW: Automatic UTM data capture and click ID detection:

Cookie Management System

NEW: Advanced cookie tracking with consent management:

Platform Management Service

NEW: Centralized platform configuration management:

📚 API Reference

Enhanced HasMarketingParameters Trait

MarketingUrlBuilder

New Services & Events

New Traits

🔄 Upgrading from v1 to v2

Migration Overview

Version 2.0 introduces major new features while maintaining 100% backward compatibility. Your existing code will continue to work without any changes, but you can opt-in to enhanced features for improved functionality.

Step 1: Update the Package

Step 2: Publish New Configuration (Optional)

To access new features, publish the updated configuration:

⚠️ Important: This will overwrite your existing config. Back up your current configuration first if you have custom settings.

Step 3: Enable New Features (Optional)

The new configuration includes several opt-in features. Enable them as needed:

Enable Enhanced Platform Support

Enable Click ID Management

Enable Events (for Analytics Integration)

Enable Auto-Observation (Advanced)

Enable Conversion Tracking

Enable E-commerce Tracking

Step 4: Update Your Code (Optional)

Your existing code will work without changes, but you can enhance it with new features:

Enhanced Click ID Access

Add New Traits for Enhanced Functionality

Use New URL Builder

Implement Event Listeners

Step 5: Test Your Implementation

After upgrading, verify everything works correctly:

Test Existing Functionality

Test New Click ID Priority

Test Platform Detection

Migration Checklist

• [ ] Backup Configuration: Save your current config/marketing-data-tracker.php
• [ ] Update Package: Run composer update marshmallow/marketing-data-tracker
• [ ] Publish Config: Run publish command if you want new features
• [ ] Enable Platforms: Configure the platforms you use
• [ ] Enable Features: Turn on click ID management, events, etc. as needed
• [ ] Update Models: Add new traits if you want conversion/e-commerce tracking
• [ ] Test Functionality: Verify existing UTM tracking still works
• [ ] Test New Features: Verify new click ID priority and platform detection
• [ ] Monitor Events: Check that events fire correctly if enabled
• [ ] Performance Test: Ensure no performance degradation

Common Migration Issues

Issue: Configuration Override

Problem: New config overwrites custom settings Solution: Merge your custom settings with the new configuration structure

Issue: Events Not Firing

Problem: Events enabled but listeners not receiving them Solution: Ensure 'events' => ['enabled' => true] and check listener registration

Issue: Platform Not Detected

Problem: Platform detection returns null Solution: Ensure the platform is enabled in the new platforms configuration

Issue: Click IDs Not Prioritized

Problem: getPrimaryGoogleClickId() returns null Solution: Enable click ID management: 'click_id_management' => ['enabled' => true]

Getting Help

If you encounter issues during migration:

1. Check Configuration: Ensure new config sections are properly configured
2. Review Logs: Look for error messages in Laravel logs
3. Test Incrementally: Enable one feature at a time to isolate issues
4. Fallback: Disable new features if needed - v1 functionality will still work

What Stays the Same

✅ All existing methods work exactly as before ✅ Database structure remains unchanged ✅ UTM parameter capture works identically ✅ Laravel Nova integration continues to work ✅ Basic click ID detection functions as before

What Gets Better

🚀 Enhanced click ID priority with configurable extraction 🚀 12+ platform support with individual controls 🚀 Advanced cookie tracking with consent management 🚀 Event-driven architecture for analytics integration 🚀 Conversion & e-commerce tracking with attribution 🚀 URL builder for campaign management 🚀 Wildcard pattern matching for flexible parameter capture

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

📄 Changelog

Please see CHANGELOG for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

💡 Use Cases

E-commerce Attribution

Track customer acquisition costs, measure ROAS, and optimize ad spend across platforms.

SaaS Conversion Tracking

Monitor trial-to-paid conversion rates by marketing channel and campaign.

Lead Generation

Attribute leads to their original marketing source for accurate ROI calculation.

Content Marketing

Track which content pieces drive the most valuable conversions.

Multi-Touch Attribution

Understand the complete customer journey across multiple touchpoints.

🏆 Why Choose This Package?

✅ Battle-Tested - Used in production by hundreds of Laravel applications

✅ Comprehensive - Supports more platforms than any other Laravel marketing package

✅ Developer Friendly - Clean API, excellent documentation, and Laravel conventions

✅ Performance Optimized - Minimal overhead with intelligent caching

✅ Privacy Compliant - Built-in GDPR support and consent management

✅ Actively Maintained - Regular updates and new platform support

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

📜 License

The MIT License (MIT). Please see License File for more information.

👏 Credits

• Marshmallow - Package development and maintenance
• All Contributors - Community contributions and feedback

Made with ❤️ by the Marshmallow team

Star ⭐ this repo if you find it helpful!