PHPackages                             marshmallow/marketing-data-tracker - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. marshmallow/marketing-data-tracker

ActiveLibrary[Utility & Helpers](/categories/utility)

marshmallow/marketing-data-tracker
==================================

Parse and store marketing parameters like gclid, utm\_\*, and adid, and automatically attach them to user conversions or models in Laravel.

v2.2.1(3w ago)31.3k—2%1[1 PRs](https://github.com/marshmallow-packages/marketing-data-tracker/pulls)MITPHPPHP ^8.0CI passing

Since Jun 6Pushed 2w agoCompare

[ Source](https://github.com/marshmallow-packages/marketing-data-tracker)[ Packagist](https://packagist.org/packages/marshmallow/marketing-data-tracker)[ Docs](https://github.com/marshmallow-packages/marketing-data-tracker)[ GitHub Sponsors](https://github.com/Marshmallow)[ RSS](/packages/marshmallow-marketing-data-tracker/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (39)Versions (27)Used By (0)

🎯 Laravel Marketing Data Tracker
================================

[](#-laravel-marketing-data-tracker)

### Comprehensive Marketing Attribution & UTM Parameter Tracking for Laravel

[](#comprehensive-marketing-attribution--utm-parameter-tracking-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/438d320a6bd5d3bf76b19392c15e27a8e2923c91ce6ee6821f1daca454698877/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d617273686d616c6c6f772f6d61726b6574696e672d646174612d747261636b65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marshmallow/marketing-data-tracker)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/8e59d9a529184a34e7dcff4ab0de3d6b71ab77f75bc7ccb5bf11b33926106693/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d617273686d616c6c6f772d7061636b616765732f6d61726b6574696e672d646174612d747261636b65722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/marshmallow-packages/marketing-data-tracker/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/cabc91412d4f564e06ebbff9d6e0164137f23941299b5f20bd1ceba710e52944/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d617273686d616c6c6f772f6d61726b6574696e672d646174612d747261636b65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marshmallow/marketing-data-tracker)

**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
----------

[](#-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
-------------

[](#-quick-start)

### Installation

[](#installation)

Install via Composer:

```
composer require marshmallow/marketing-data-tracker
```

Publish and run migrations:

```
php artisan vendor:publish --tag="marketing-data-tracker-migrations"
php artisan migrate
```

### Basic Setup

[](#basic-setup)

**1. Add the trait to your models:**

```
use Marshmallow\MarketingData\Traits\HasMarketingParameters;

class User extends Model
{
    use HasMarketingParameters;

    // Your model code...
}
```

**2. Add the middleware to your web routes:**

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

```
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Marshmallow\MarketingData\Middleware\ParseMarketingParameters::class,
    ]);
})
```

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

```
protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \Marshmallow\MarketingData\Middleware\ParseMarketingParameters::class,
    ],
];
```

**3. Track marketing data on user registration:**

```
// Automatically capture and store marketing data
$user = User::create($userData);
$user->setUtmSourceData(); // Captures all marketing parameters from session

// Access marketing data
echo $user->utm_source;     // "google"
echo $user->utm_campaign;   // "summer-sale-2024"
echo $user->primary_click_id; // "gclid_abc123..."
echo $user->platform_name;  // "Google Ads"
```

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

---

📖 Platform Support
------------------

[](#-platform-support)

### Enhanced Multi-Platform System

[](#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

[](#supported-advertising-platforms)

PlatformClick IDUTM SourceCustom ParametersStatus**Google Ads**`gclid`, `gbraid`, `wbraid``google`20+ ValueTrack parameters✅ Enhanced**Meta/Facebook**`fbclid``facebook`, `meta`Dynamic campaign parameters✅ Enhanced**Microsoft Ads**`msclkid``bing`, `microsoft`UET tracking parameters✅ Enhanced**LinkedIn Ads**`li_fat_id``linkedin`Professional network parameters✅ Enhanced**Twitter/X Ads**`twclid``twitter`, `x`Social media parameters✅ Enhanced**Pinterest Ads**`epik``pinterest`Visual platform parameters✅ Enhanced**TikTok Ads**`ttclid``tiktok`Short-form video parameters✅ Enhanced**Reddit Ads**`rdt_cid``reddit`Community platform parameters✅ Enhanced**Snapchat Ads**`sscid``snapchat`Mobile-first parameters✅ Enhanced**Amazon DSP**`maas``amazon`E-commerce advertising✅ Enhanced**TradeTracker**`ttid``tradetracker`Affiliate network tracking✅ New**Email Marketing**`mc_cid`, `mc_eid``email`Campaign tracking✅ New#### Platform Configuration

[](#platform-configuration)

Each platform can be individually enabled/disabled and configured:

```
// config/marketing-data-tracker.php
'platforms' => [
    'google_ads' => [
        'enabled' => true,
        'name' => 'Google Ads',
        'click_id_params' => ['gclid', 'gbraid', 'wbraid'],
        'click_id_cookies' => ['_gcl_aw', '_gcl_gb', '_gcl_ag'],
        'parameters' => [
            'gclid', 'gbraid', 'wbraid', 'gad_source', 'mm_campaignid',
            'mm_adgroupid', 'mm_keyword', 'mm_matchtype', 'mm_network',
            'mm_device', 'mm_placement', // ... and 15+ more
        ],
        'cookies' => ['_ga', '_gid', '_gcl_*', '_ga*'], // Supports wildcards
    ],
    // ... more platforms
],
```

### Automatic Parameter Detection

[](#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
----------------

[](#-usage-examples)

### Basic Marketing Attribution

[](#basic-marketing-attribution)

```
// Create user and automatically capture marketing data
$user = User::create($userData);
$user->setUtmSourceData();

// Access marketing information
echo $user->marketing_source;        // "Google"
echo $user->utm_source_medium;       // "Google - Cpc"
echo $user->utm_campaign_term;       // "Summer Sale - running shoes"
```

### Advanced Click ID Management

[](#advanced-click-id-management)

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

```
// Get the highest priority click ID from any platform
$clickId = $user->primary_click_id;  // Automatically prioritizes gclid > fbclid > ttclid

// Get Google-specific click ID with priority handling
$googleClickId = $user->getPrimaryGoogleClickId(); // gclid > wbraid > gbraid

// Check specific platform attribution
if ($user->has_google_id) {
    $googleIds = $user->google_ids;   // ['gclid' => '...', 'gbraid' => '...']
}

// Platform detection
$platform = $user->platform_name;    // "Google Ads", "Meta/Facebook", "TikTok"
$platformKey = $user->detectPlatformFromMarketingData(); // "google_ads", "meta", "tiktok"
```

#### Click ID Priority Configuration

[](#click-id-priority-configuration)

```
// config/marketing-data-tracker.php
'click_id_management' => [
    'enabled' => true,
    'google_click_ids' => [
        'enabled' => true,
        'priority' => ['gclid', 'wbraid', 'gbraid'],
        'cookie_mapping' => [
            'gclid' => '_gcl_aw',
            'wbraid' => '_gcl_gb',
            'gbraid' => '_gcl_ag',
        ],
        'extract_gclid_value' => true, // Extract clean ID from cookie format
    ],
    'platform_priority' => [
        'gclid' => 10,    // Google Ads - highest priority
        'fbclid' => 9,    // Facebook/Meta
        'msclkid' => 8,   // Microsoft/Bing
        'ttclid' => 7,    // TikTok
        // ... more platforms
    ],
],
```

### E-commerce Conversion Tracking

[](#e-commerce-conversion-tracking)

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

```
use Marshmallow\MarketingData\Traits\TracksEcommerceEvents;
use Marshmallow\MarketingData\Traits\TracksConversions;

class Order extends Model
{
    use HasMarketingParameters, TracksEcommerceEvents, TracksConversions;
}

// Track purchase conversion with attribution
$order = Order::create($orderData);
$order->setUtmSourceData();
$order->trackPurchase('TXN-123', $products, 299.99, 'EUR');

// Track other e-commerce events
$product->trackViewItem();
$product->trackAddToCart(2); // quantity
$order->trackBeginCheckout($items, $total);

// Track conversions with attribution
$lead->trackLeadConversion(50.00);
$user->trackSignupConversion();
$subscription->trackSubscriptionConversion(99.99, 'USD');
```

#### E-commerce Configuration

[](#e-commerce-configuration)

```
// config/marketing-data-tracker.php
'ecommerce' => [
    'enabled' => true,
    'currency' => 'EUR',
    'events' => [
        'view_item' => true,
        'add_to_cart' => true,
        'purchase' => true,
    ],
    'gtm_format' => true,
    'platform_formats' => [
        'google_ads' => true,
        'meta' => true,
    ],
],

'conversions' => [
    'enabled' => true,
    'types' => [
        'lead' => ['value' => null, 'priority' => 1],
        'purchase' => ['value' => null, 'priority' => 5],
    ],
    'auto_track' => false,
    'track_value' => true,
],
```

### Campaign Performance Analysis

[](#campaign-performance-analysis)

```
// Get all users from Google Ads campaigns
$googleUsers = User::whereNotNull('gclid')->get();

// Group by campaign
$campaignPerformance = User::select('utm_campaign')
    ->selectRaw('COUNT(*) as users, SUM(conversion_value) as revenue')
    ->groupBy('utm_campaign')
    ->get();

// Platform breakdown
$platformStats = User::selectRaw('
    CASE
        WHEN gclid IS NOT NULL THEN "Google Ads"
        WHEN fbclid IS NOT NULL THEN "Facebook"
        WHEN ttclid IS NOT NULL THEN "TikTok"
        ELSE "Other"
    END as platform,
    COUNT(*) as count
')->groupBy('platform')->get();
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag="marketing-data-tracker-config"
```

### Platform-Specific Configuration

[](#platform-specific-configuration)

```
// config/marketing-data-tracker.php

'platforms' => [
    'google_ads' => [
        'click_id_params' => ['gclid', 'wbraid', 'gbraid'],
        'click_id_cookies' => ['_gcl_aw', '_gcl_gb', '_gcl_ag'],
        'custom_params' => [
            'mm_campaignid' => '{campaignid}',
            'mm_keyword' => '{keyword}',
            // ... more ValueTrack parameters
        ],
    ],
    'meta' => [
        'click_id_params' => ['fbclid'],
        'click_id_cookies' => ['_fbp', 'fbc'],
        'custom_params' => [
            'mm_campaignid' => '{{campaign.id}}',
            'mm_placement' => '{{placement}}',
            // ... more dynamic parameters
        ],
    ],
    // ... other platforms
],
```

### Cookie Consent Management

[](#cookie-consent-management)

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

```
'cookie_management' => [
    'enabled' => true,
    'groups' => [
        'analytics' => ['cookies' => ['_ga', '_gid', '_ga_*'], 'required' => false],
        'advertising' => ['cookies' => ['_gcl_*', '_fbp', 'fbc'], 'required' => false],
        'functional' => ['cookies' => ['session_id'], 'required' => true],
    ],
    'consent' => [
        'enabled' => false,
        'cookie_name' => 'cookie_consent',
        'respect_consent' => true,
        'default_consent' => [
            'functional' => true,
            'analytics' => false,
            'advertising' => false,
        ],
    ],
    'wildcard_support' => true,
    'auto_register_exceptions' => true,
],
```

> 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
-------------------

[](#-advanced-features)

### Marketing URL Builder

[](#marketing-url-builder)

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

```
use Marshmallow\MarketingData\Builders\MarketingUrlBuilder;

// Build Google Ads URLs with ValueTrack parameters
$url = MarketingUrlBuilder::googleAds('https://example.com', 'summer-sale')
    ->withGoogleValueTrack()
    ->build();
// Result: https://example.com?utm_source=google&utm_medium=cpc&gclid={gclid}&mm_campaignid={campaignid}...

// Build Meta/Facebook Ads URLs with dynamic parameters
$url = MarketingUrlBuilder::metaAds('https://example.com', 'awareness-campaign')
    ->withMetaDynamicParams()
    ->build();
// Result: https://example.com?utm_source=facebook&fbclid={{fbclid}}&mm_campaignid={{campaign.id}}...

// Build Microsoft Ads URLs
$url = MarketingUrlBuilder::microsoftAds('https://example.com', 'search-campaign')
    ->build();

// Build LinkedIn Ads URLs
$url = MarketingUrlBuilder::linkedInAds('https://example.com', 'b2b-campaign')
    ->build();

// Custom UTM URLs
$url = MarketingUrlBuilder::utm(
    'https://example.com',
    'newsletter',
    'email',
    'weekly-digest'
);

// Advanced usage with custom parameters
$url = MarketingUrlBuilder::make('https://example.com')
    ->withUTM('google', 'cpc', 'summer-sale')
    ->withPlatform('google_ads', ['mm_keyword' => 'running shoes'])
    ->withCustomParams(['custom_param' => 'value'])
    ->build();

// Use tracking templates from config
$url = MarketingUrlBuilder::fromTemplate(
    'https://example.com',
    'google_ads',
    ['campaignid' => '12345', 'keyword' => 'shoes']
);
```

#### URL Builder Features

[](#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

[](#event-driven-architecture)

**NEW**: Comprehensive event system for marketing data lifecycle tracking:

```
use Marshmallow\MarketingData\Events\MarketingDataCreated;
use Marshmallow\MarketingData\Events\MarketingDataUpdated;
use Marshmallow\MarketingData\Events\ConversionTracked;
use Marshmallow\MarketingData\Events\ClickIdDetected;

// Listen to marketing data creation
Event::listen(MarketingDataCreated::class, function ($event) {
    // Send to analytics when marketing data is first captured
    Analytics::trackAcquisition($event->model, $event->getCreatedData());
});

// Listen to click ID detection
Event::listen(ClickIdDetected::class, function ($event) {
    // Store click ID for server-side conversion tracking
    if ($event->isGoogleClickId()) {
        Redis::setex("gclid:{$event->clickId}", 3600, $event->getSessionData());
    }
});

// Listen to conversions
Event::listen(ConversionTracked::class, function ($event) {
    // Send conversion data to multiple platforms
    if ($event->hasValue()) {
        GoogleAds::trackConversion($event->getRevenueAttribution());
        FacebookConversions::track($event->getConversionData());
    }
});

// Listen to marketing data updates
Event::listen(MarketingDataUpdated::class, function ($event) {
    if ($event->hasClickIdChanges()) {
        // Handle click ID changes
        logger()->info('Click ID changed', $event->getClickIdChanges());
    }
});
```

#### Event Configuration

[](#event-configuration)

```
// config/marketing-data-tracker.php
'events' => [
    'enabled' => true,
    'listeners' => [
        'Marshmallow\\MarketingData\\Events\\ConversionTracked' => [
            'App\\Listeners\\SendToGoogleAds',
            'App\\Listeners\\SendToFacebookConversions',
        ],
    ],
],
```

### Laravel Nova Integration

[](#laravel-nova-integration)

```
use Marshmallow\MarketingData\Nova\Traits\MarketingDataFields;

class UserResource extends Resource
{
    use MarketingDataFields;

    public function fields(Request $request)
    {
        return [
            // ... your fields

            ...$this->getMarketingDataFields(
                with_utm_data: true,
                with_google_ids: true,
                with_all_data: false,
            ),
        ];
    }
}
```

---

🎨 Platform-Specific Setup
-------------------------

[](#-platform-specific-setup)

### Google Ads Configuration

[](#google-ads-configuration)

Add to your Google Ads account-level tracking template:

```
?utm_source=google&utm_medium=cpc&utm_campaign={_campaign}&utm_term={keyword}&utm_content={creative}&mm_campaignid={campaignid}&mm_adgroupid={adgroupid}&mm_keyword={keyword}&mm_matchtype={matchtype}&mm_network={network}&mm_device={device}&mm_placement={placement}&gclid={gclid}&gbraid={gbraid}&wbraid={wbraid}

```

### Facebook Ads Configuration

[](#facebook-ads-configuration)

Use Facebook's URL parameters in your ads:

```
?utm_source=facebook&utm_medium=paid&utm_campaign={{campaign.name}}&utm_content={{ad.name}}&utm_term={{adset.name}}&fbclid={{fbclid}}

```

### Server-Side Tracking Setup

[](#server-side-tracking-setup)

For accurate attribution, configure server-side tracking:

```
// Track conversions server-side
$user->trackConversion('purchase', 99.99, 'USD', [
    'order_id' => 'ORD-123',
    'products' => $products,
]);
```

---

🏗️ Architecture
---------------

[](#️-architecture)

### Database Schema

[](#database-schema)

The package creates a flexible marketing data storage system:

```
-- marketing_data stored as JSON in your existing models
{
    "utm_source": "google",
    "utm_campaign": "summer-sale",
    "gclid": "Cj0KCQiA...",
    "mm_keyword": "running shoes",
    "platform": "google_ads"
}
```

### Privacy & GDPR Compliance

[](#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
-----------------------

[](#-analytics-integration)

### Google Analytics 4

[](#google-analytics-4)

```
// Send conversion data to GA4
$user->trackConversion('purchase', 199.99);
// Automatically includes marketing attribution data
```

### Facebook Conversions API

[](#facebook-conversions-api)

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

```
use Marshmallow\MarketingData\Events\ConversionTracked;

Event::listen(ConversionTracked::class, function (ConversionTracked $event) {
    FacebookConversions::send('Purchase', [
        'value' => $event->conversionValue,
        'currency' => $event->conversionCurrency,
        'attribution' => $event->getAttributionData(),
    ]);
});
```

### Custom Analytics Platforms

[](#custom-analytics-platforms)

```
// Send to any analytics platform
Event::listen(ConversionTracked::class, function ($event) {
    CustomAnalytics::track([
        'event' => $event->conversionType,
        'value' => $event->conversionValue,
        'attribution' => $event->getAttributionData(),
    ]);
});
```

---

🧪 Testing
---------

[](#-testing)

```
# Run the test suite
composer test

# Run with coverage
composer test-coverage
```

### Testing Marketing Attribution

[](#testing-marketing-attribution)

```
// Test marketing data capture
$this->get('/?utm_source=google&utm_campaign=test&gclid=123');

$user = User::factory()->create();
$user->setUtmSourceData();

$this->assertEquals('google', $user->utm_source);
$this->assertEquals('123', $user->gclid);
```

---

🚀 Performance
-------------

[](#-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
------------------------

[](#️-new-advanced-features)

### Automatic Model Observation

[](#automatic-model-observation)

**NEW**: Automatic UTM data capture and click ID detection:

```
// config/marketing-data-tracker.php
'observers' => [
    'enabled' => true,
    'models' => [
        App\Models\Lead::class,
        App\Models\Order::class,
    ],
    'auto_set_utm' => true,
    'auto_detect_click_ids' => true,
    'forget_after_save' => true,
],
```

### Cookie Management System

[](#cookie-management-system)

**NEW**: Advanced cookie tracking with consent management:

```
use Marshmallow\MarketingData\Services\CookieManager;

$cookieManager = app(CookieManager::class);

// Get trackable cookies with consent filtering
$cookies = $cookieManager->getCookieValues($request);

// Check consent for specific groups
if ($cookieManager->isTrackingAllowed('advertising')) {
    // Track advertising cookies
}

// Wildcard cookie matching
$matches = $cookieManager->matchWildcardCookies(
    ['_ga_123', '_ga_456', '_fbp'],
    ['_ga*']
); // Returns: ['_ga_123', '_ga_456']
```

### Platform Management Service

[](#platform-management-service)

**NEW**: Centralized platform configuration management:

```
use Marshmallow\MarketingData\Services\PlatformManager;

$platformManager = app(PlatformManager::class);

// Get enabled platforms
$platforms = $platformManager->getEnabledPlatforms();

// Get platform-specific parameters
$googleParams = $platformManager->getPlatformParameters('google_ads');

// Get all tracking parameters across platforms
$allParams = $platformManager->getAllTrackingParameters();

// Wildcard pattern matching
$matches = $platformManager->matchWildcardPatterns(
    ['utm_source', 'utm_campaign', 'gclid'],
    ['utm_*']
); // Returns: ['utm_source', 'utm_campaign']
```

---

📚 API Reference
---------------

[](#-api-reference)

### Enhanced HasMarketingParameters Trait

[](#enhanced-hasmarketingparameters-trait)

MethodDescriptionExample`setUtmSourceData()`Capture marketing parameters`$user->setUtmSourceData()``getPrimaryGoogleClickId()`**NEW**: Get Google click ID with priority`$user->getPrimaryGoogleClickId()``primary_click_id`Get highest priority click ID`$user->primary_click_id``platform_name`Get platform name`$user->platform_name``detectPlatformFromMarketingData()`Detect advertising platform`$user->detectPlatformFromMarketingData()``marketing_parameter_list`Get formatted parameters`$user->marketing_parameter_list`### MarketingUrlBuilder

[](#marketingurlbuilder)

MethodDescriptionExample`googleAds()`Build Google Ads URL`MarketingUrlBuilder::googleAds($url, $campaign)``metaAds()`Build Facebook Ads URL`MarketingUrlBuilder::metaAds($url, $campaign)``microsoftAds()`**NEW**: Build Microsoft Ads URL`MarketingUrlBuilder::microsoftAds($url, $campaign)``linkedInAds()`**NEW**: Build LinkedIn Ads URL`MarketingUrlBuilder::linkedInAds($url, $campaign)``withUTM()`Add UTM parameters`$builder->withUTM($params)``withGoogleValueTrack()`**NEW**: Add ValueTrack parameters`$builder->withGoogleValueTrack()``withPlatform()`**NEW**: Add platform-specific params`$builder->withPlatform('google_ads', $params)`### New Services & Events

[](#new-services--events)

Service/EventDescriptionExample`PlatformManager`**NEW**: Platform configuration management`$manager->getEnabledPlatforms()``CookieManager`**NEW**: Cookie tracking with consent`$manager->getCookieValues($request)``MarketingDataCreated`**NEW**: Marketing data creation event`Event::listen(MarketingDataCreated::class, ...)``ConversionTracked`**NEW**: Conversion tracking event`Event::listen(ConversionTracked::class, ...)``ClickIdDetected`**NEW**: Click ID detection event`Event::listen(ClickIdDetected::class, ...)`### New Traits

[](#new-traits)

TraitDescriptionExample`TracksConversions`**NEW**: Conversion tracking functionality`$model->trackLeadConversion(50.00)``TracksEcommerceEvents`**NEW**: E-commerce event tracking`$product->trackViewItem()`---

🔄 Upgrading from v1 to v2
-------------------------

[](#-upgrading-from-v1-to-v2)

### Migration Overview

[](#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-1-update-the-package)

```
composer update marshmallow/marketing-data-tracker
```

### Step 2: Publish New Configuration (Optional)

[](#step-2-publish-new-configuration-optional)

To access new features, publish the updated configuration:

```
php artisan vendor:publish --tag="marketing-data-tracker-config" --force
```

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

### Step 3: Enable New Features (Optional)

[](#step-3-enable-new-features-optional)

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

#### Enable Enhanced Platform Support

[](#enable-enhanced-platform-support)

```
// config/marketing-data-tracker.php
'platforms' => [
    'google_ads' => ['enabled' => true],
    'meta' => ['enabled' => true],
    'microsoft' => ['enabled' => true],
    'linkedin' => ['enabled' => true],
    'twitter' => ['enabled' => true],
    'pinterest' => ['enabled' => true],
    'tiktok' => ['enabled' => true],
    // ... enable platforms you use
],
```

#### Enable Click ID Management

[](#enable-click-id-management)

```
'click_id_management' => [
    'enabled' => true,
    'google_click_ids' => [
        'enabled' => true,
        'extract_gclid_value' => true, // Clean extraction from cookie format
    ],
],
```

#### Enable Events (for Analytics Integration)

[](#enable-events-for-analytics-integration)

```
'events' => [
    'enabled' => true,
    'listeners' => [
        // Add your custom event listeners here
    ],
],
```

#### Enable Auto-Observation (Advanced)

[](#enable-auto-observation-advanced)

```
'observers' => [
    'enabled' => true, // Only enable if you want automatic UTM capture
    'models' => [
        App\Models\Lead::class,
        App\Models\Order::class,
        // Add models that should auto-capture marketing data
    ],
    'auto_set_utm' => true,
    'auto_detect_click_ids' => true,
],
```

#### Enable Conversion Tracking

[](#enable-conversion-tracking)

```
'conversions' => [
    'enabled' => true,
    'types' => [
        'lead' => ['value' => null, 'priority' => 1],
        'purchase' => ['value' => null, 'priority' => 5],
        // Add your conversion types
    ],
],
```

#### Enable E-commerce Tracking

[](#enable-e-commerce-tracking)

```
'ecommerce' => [
    'enabled' => true,
    'currency' => 'EUR', // Your default currency
    'events' => [
        'view_item' => true,
        'add_to_cart' => true,
        'purchase' => true,
    ],
],
```

### Step 4: Update Your Code (Optional)

[](#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

[](#enhanced-click-id-access)

```
// v1 - Still works
$clickId = $user->primary_click_id;

// v2 - Enhanced with priority and extraction
$googleClickId = $user->getPrimaryGoogleClickId(); // gclid > wbraid > gbraid
```

#### Add New Traits for Enhanced Functionality

[](#add-new-traits-for-enhanced-functionality)

```
use Marshmallow\MarketingData\Traits\HasMarketingParameters;
use Marshmallow\MarketingData\Traits\TracksConversions;
use Marshmallow\MarketingData\Traits\TracksEcommerceEvents;

class Order extends Model
{
    use HasMarketingParameters, TracksConversions, TracksEcommerceEvents;

    // Your existing code remains unchanged
}

// New functionality available
$order->trackPurchase('TXN-123', $products, 299.99, 'EUR');
$order->trackConversion('purchase', 299.99);
```

#### Use New URL Builder

[](#use-new-url-builder)

```
use Marshmallow\MarketingData\Builders\MarketingUrlBuilder;

// Build campaign URLs with platform-specific parameters
$url = MarketingUrlBuilder::googleAds('https://example.com', 'summer-sale')
    ->withGoogleValueTrack()
    ->build();

// Or use the fluent interface
$url = MarketingUrlBuilder::make('https://example.com')
    ->withUTM('google', 'cpc', 'campaign')
    ->withPlatform('google_ads', ['mm_keyword' => 'shoes'])
    ->build();
```

#### Implement Event Listeners

[](#implement-event-listeners)

```
// app/Providers/EventServiceProvider.php
use Marshmallow\MarketingData\Events\ConversionTracked;
use Marshmallow\MarketingData\Events\ClickIdDetected;

protected $listen = [
    ConversionTracked::class => [
        App\Listeners\SendConversionToAnalytics::class,
    ],
    ClickIdDetected::class => [
        App\Listeners\StoreClickIdForServerSideTracking::class,
    ],
];
```

### Step 5: Test Your Implementation

[](#step-5-test-your-implementation)

After upgrading, verify everything works correctly:

#### Test Existing Functionality

[](#test-existing-functionality)

```
// Ensure your existing UTM tracking still works
$this->get('/?utm_source=google&utm_campaign=test&gclid=123');

$user = User::factory()->create();
$user->setUtmSourceData();

$this->assertEquals('google', $user->utm_source);
$this->assertEquals('123', $user->gclid);
```

#### Test New Click ID Priority

[](#test-new-click-id-priority)

```
$user = new User();
$user->setUtmSourceData(); // Assume session has gclid, wbraid, gbraid

// Should return gclid (highest priority)
$primaryGoogle = $user->getPrimaryGoogleClickId();

// Should return highest priority overall
$primaryAny = $user->primary_click_id;
```

#### Test Platform Detection

[](#test-platform-detection)

```
$user->gclid = 'test_gclid';
$platform = $user->platform_name; // Should return "Google Ads"

$user->fbclid = 'test_fbclid';
$platform = $user->platform_name; // Should return "Meta/Facebook"
```

### Migration Checklist

[](#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

[](#common-migration-issues)

#### Issue: Configuration Override

[](#issue-configuration-override)

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

#### Issue: Events Not Firing

[](#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

[](#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

[](#issue-click-ids-not-prioritized)

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

### Getting Help

[](#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

[](#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

[](#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
--------------

[](#-contributing)

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development Setup

[](#development-setup)

```
git clone https://github.com/marshmallow-packages/marketing-data-tracker
cd marketing-data-tracker
composer install
composer test
```

---

📄 Changelog
-----------

[](#-changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

---

🔒 Security
----------

[](#-security)

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

---

💡 Use Cases
-----------

[](#-use-cases)

### E-commerce Attribution

[](#e-commerce-attribution)

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

### SaaS Conversion Tracking

[](#saas-conversion-tracking)

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

### Lead Generation

[](#lead-generation)

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

### Content Marketing

[](#content-marketing)

Track which content pieces drive the most valuable conversions.

### Multi-Touch Attribution

[](#multi-touch-attribution)

Understand the complete customer journey across multiple touchpoints.

---

🏆 Why Choose This Package?
--------------------------

[](#-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
---------

[](#-support)

- **Issues**: [GitHub Issues](https://github.com/marshmallow-packages/marketing-data-tracker/issues)
- **Discussions**: [GitHub Discussions](https://github.com/marshmallow-packages/marketing-data-tracker/discussions)
- **Email**:

---

📜 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

---

👏 Credits
---------

[](#-credits)

- **[Marshmallow](https://github.com/marshmallow-packages)** - Package development and maintenance
- **[All Contributors](../../contributors)** - Community contributions and feedback

---

**Made with ❤️ by the Marshmallow team**

*Star ⭐ this repo if you find it helpful!*

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance96

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~22 days

Recently: every ~29 days

Total

18

Last Release

23d ago

Major Versions

v1.1.0 → v2.0.12025-08-04

v1.2.1 → v2.0.0.x-dev2026-02-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/be33d2624e24c516e73892b0929447cc762f3622c024ab8d0d2a59042e5d2c7f?d=identicon)[marshmallow](/maintainers/marshmallow)

---

Top Contributors

[![LTKort](https://avatars.githubusercontent.com/u/2412670?v=4)](https://github.com/LTKort "LTKort (101 commits)")[![stefvanesch](https://avatars.githubusercontent.com/u/46725619?v=4)](https://github.com/stefvanesch "stefvanesch (10 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")[![milan607](https://avatars.githubusercontent.com/u/258212842?v=4)](https://github.com/milan607 "milan607 (1 commits)")

---

Tags

laravelmarshmallowmarketing-data-tracker

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/marshmallow-marketing-data-tracker/health.svg)

```
[![Health](https://phpackages.com/badges/marshmallow-marketing-data-tracker/health.svg)](https://phpackages.com/packages/marshmallow-marketing-data-tracker)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[codewithdennis/filament-select-tree

The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths.

329530.5k29](/packages/codewithdennis-filament-select-tree)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[worksome/exchange

Check Exchange Rates for any currency in Laravel.

124603.0k](/packages/worksome-exchange)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.4k](/packages/tarfin-labs-event-machine)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)