README

A unified package for managing multiple advertising platform pixels (Facebook, TikTok, Snapchat) in Laravel applications with server-side conversion tracking.

Features

📊 Multi-Platform Support: Built-in support for Facebook, TikTok, and Snapchat
🎯 Selective Targeting: Target specific platforms or pixels for each event
🔄 Queue-Based Processing: Zero performance impact with async event processing
🔒 Secure Credentials: AES-256 encryption for access tokens
🛡️ GDPR/CCPA Compliant: Built-in consent management
📝 Blade Directives: Easy-to-use directives for script injection
⚡ Smart Deduplication: Prevent duplicate events with cache-based deduplication

Installation

You can install the package via composer:

composer require ideacrafters/laravel-pixels-manager

Run the installation wizard:

php artisan pixel:install

Add your first pixel:

php artisan pixel:add

Usage

Basic Tracking

Track events across all configured platforms:

use Ideacrafters\PixelManager\Facades\PixelManager;

PixelManager::track('Purchase', [
    'value' => 99.99,
    'currency' => 'USD',
]);

Selective Tracking

Track to specific platforms:

PixelManager::forPlatforms('facebook', 'tiktok')
    ->track('ViewContent', [
        'content_id' => 'SKU123',
        'value' => 29.99,
    ]);

Track to specific pixels:

PixelManager::forPixels(1, 3)
    ->track('AddToCart', [
        'content_id' => 'SKU123',
        'value' => 29.99,
    ]);

Exclude platforms:

PixelManager::except('snapchat')
    ->track('PageView');

Blade Directives

Add to your layout's <head> section:

<head>
    @pixels
    <!-- Your other head content -->
</head>

Load specific platforms:

@pixels('facebook', 'tiktok')

Add noscript fallbacks:

<noscript>
    @pixelsNoscript
</noscript>

Model Integration

Add the TrackableEvents trait to your User or Order model:

use Ideacrafters\PixelManager\Traits\TrackableEvents;

class User extends Authenticatable
{
    use TrackableEvents;
}

Now track events directly on your models:

$user->trackPurchase(99.99, 'USD');
$user->trackAddToCart($product->id, $product->price);
$user->trackViewContent($product->id, $product->name, $product->price);

Passing Browser Context (Queue-Safe CAPI)

When tracking from HTTP context but dispatching via queue, pass browser data through extraUserData:

$user->trackEvent('Purchase', [
    'value' => 29.99,
    'currency' => 'USD',
    'event_id' => 'your-dedup-id',           // optional: for client-server dedup
    'event_source_url' => request()->fullUrl(), // optional: captured before queue
], extraUserData: [
    'client_ip_address' => request()->ip(),
    'client_user_agent' => request()->userAgent(),
    'fbp' => request()->cookie('_fbp'),
    'fbc' => request()->cookie('_fbc'),
]);

When running in queue/console context, the package automatically:

Falls back to config('app.url') for event_source_url
Uses $userData['client_ip_address'] for event ID generation instead of request()->ip()
Passes external_id through to Meta's CAPI user_data

Artisan Commands

# Install and setup
php artisan pixel:install

# Add a new pixel
php artisan pixel:add

# Test a pixel configuration
php artisan pixel:test {id}

Configuration

The configuration file includes:

Platform adapter mappings
Queue connection settings
Deduplication settings
Standard event definitions
Cache configuration

See config/pixels-manager.php for all available options.

Requirements

PHP >= 8.0
Laravel >= 9.0
Queue driver: Redis (recommended) or Database
Cache driver: Redis (recommended) or Memcached

Testing

composer test

Security

AES-256 encryption for credentials stored in database
SHA-256 hashing for PII (emails, phones) before sending
HTTPS-only API communication
Input validation and sanitization
GDPR/CCPA consent management

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

ideacrafters/laravel-pixels-manager

包简介

关键字：

README 文档