rsmmonaem/laravel-meta-ads-attribution

Production-ready Meta/Facebook Ads attribution, customer journey tracking, order attribution, and delivered-order Conversions API (CAPI) system for Laravel e-commerce.

Maintainers

Package info

github.com/rsmmonaem/laravel-meta-ads-attribution

pkg:composer/rsmmonaem/laravel-meta-ads-attribution

Transparency log

Statistics

Installs: 5

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.3 2026-08-24 21:48 UTC

Requires

MIT ced4ddcd7b598cfba3328feb87b52664c9a2e0f7

  • RsmMonaem <vrkm55.woop@gmail.com>

ecommercefacebooklaravelmetaattributioncapifacebook-pixelconversions-apiutm-trackingfbcliddelivered-order-conversions

Published on Packagist.org on 2026-08-24 21:49 UTC

This package is not auto-updated.

Last update: 2026-08-25 07:16:34 UTC

README

Latest Version on Packagist Total Downloads License

Production-ready end-to-end Meta/Facebook Ads attribution, customer journey tracking, order attribution, and qualified DELIVERED order Conversions API (CAPI) system for ANY Laravel application (custom e-commerce, Bagisto, Lunar, Shopper, Filament, Nova, Aimeos).

🌟 Key Features

  • First-Party Click & Landing Attribution Engine: Captures fbclid, utm_source, utm_medium, utm_campaign, utm_term, utm_content, _fbp, _fbc, landing page, referrer, IP address, user-agent.
  • First-Party Visitor Tracking: Sets a 90-day visitor cookie (meta_visitor_id) that persists across page browsing, cart additions, login, registration, and guest checkout.
  • Hybrid / First Paid Touch Attribution: Preserves original acquisition ad campaign while tracking latest touchpoint.
  • Meta Conversions API (CAPI): Normalizes and SHA-256 hashes PII (em, ph, fn, ln, ct, st, zp, country, external_id) while transmitting unhashed technical parameters (client_ip_address, client_user_agent, fbp, fbc).
  • Qualified DELIVERED Conversion Trigger: Fires Meta CAPI Purchase conversion ONLY when an order status reaches DELIVERED (or configured status).
  • Strict Idempotency & Deduplication: Guarantees duplicate status changes to DELIVERED do NOT produce duplicate CAPI dispatches (tracked by deterministic event ID purchase_{order_id}).
  • Asynchronous Queue & Retries: Queued dispatches (SendMetaDeliveredConversionJob) with 5 retries and exponential backoff (10s, 60s, 300s, 900s, 3600s).
  • Admin Dashboard & Audit Log: Analytics UI (/admin/meta-attribution) showing Meta visitors, sessions, orders, delivered orders, revenue, campaign performance breakdown, and log with manual event retry.

📥 Installation

composer require rsmmonaem/laravel-meta-ads-attribution

⚙️ Package Setup

Run the automated installer command:

php artisan meta-attribution:install

This will publish:

  • config/meta-attribution.php
  • Database Migrations
  • Admin Blade views

Then run migrations:

php artisan migrate

🔧 Environment Configuration

Add your Meta credentials to your .env file:

META_ATTRIBUTION_ENABLED=true
META_ENABLE_BROWSER_PIXEL=true
META_ENABLE_CAPI=true
META_PIXEL_ID=123456789012345
META_ACCESS_TOKEN=EAAB1234567890...
META_TEST_EVENT_CODE=  # Optional: set to test code during Meta Events Manager testing
META_QUALIFIED_ORDER_STATUS=delivered
META_ATTRIBUTION_MODEL=first_paid_touch

🚀 How to Integrate into Your Laravel Models & Views

1. Register Middleware

In Laravel 11+: Add CaptureMetaAttributionMiddleware in bootstrap/app.php:

use RsmMonaem\MetaAdsAttribution\Middleware\CaptureMetaAttributionMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        CaptureMetaAttributionMiddleware::class,
    ]);
})

In Laravel 10 or earlier: Add CaptureMetaAttributionMiddleware::class to $middlewareGroups['web'] in app/Http/Kernel.php.

2. Attach Trait to Your Order Model

Add HasMetaAttribution to any Order Eloquent model (App\Models\Order, Lunar\Models\Order, etc.):

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use RsmMonaem\MetaAdsAttribution\Traits\HasMetaAttribution;

class Order extends Model
{
    use HasMetaAttribution;
}

3. Add @metaPixel to Your Blade Layout <head>

In your main resources/views/layouts/app.blade.php:

<head>
    <meta charset="UTF-8">
    <title>My Store</title>
    
    @metaPixel
</head>

📊 Admin Dashboard

Access the built-in attribution & CAPI audit log dashboard at:

https://yourdomain.com/admin/meta-attribution

Features:

  • Real-time Meta traffic, session, order, and revenue metrics.
  • Campaign breakdown by utm_campaign.
  • Conversions API audit log with status badges (sent, failed, pending).
  • One-click Retry button for failed API requests.

🧪 Testing

Run the automated PHPUnit / Pest test suite:

php artisan test

📄 License

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