Analytics Meta Filament Laravel Package

Getting Started

This package is the Filament presentation adapter for Liberu's Meta (Facebook) server-side tracking module. It almost certainly contains no tracking logic itself — it wires the underlying analytics/meta domain package into a Filament panel (settings pages, event-mapping resources, dispatch logs). Before anything else, confirm that assumption.

Step 1 — Verify the dependency chain. Open composer.json in the repo and look at require. You want to see the core domain package (something like liberusoftware/module-analytics-meta) listed. If it is only a suggest, you must install that separately or the adapter will fail at runtime with container-resolution errors.

Step 2 — Install and publish.

composer require liberusoftware/analytics-meta-filament
php artisan vendor:publish --provider="Liberu\Analytics\Meta\Filament\AnalyticsMetaFilamentServiceProvider"
php artisan migrate

Step 3 — Register the plugin with your panel. This is the entry point for the whole package:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(\Liberu\Analytics\Meta\Filament\AnalyticsMetaFilamentPlugin::make());
}

The exact FQCN is the first thing to confirm — grep src/ for implements Plugin (Filament v3/v4) or implements FilamentPlugin.

Step 4 — Where to look first. In this order:

1. src/*ServiceProvider.php — reveals bindings, config keys, migration paths, and which contracts get resolved.
2. config/ — the pixel ID, CAPI access token, and test-event-code keys. Copy these to .env immediately; never let them live in committed config.
3. src/Filament/ — the Resources and Pages. This is your entire UI surface: what the admin can configure and what they can see.
4. src/Adapters/ or src/Presenters/ — the glue between domain events and Filament table/widget data.

First use case. Authenticate as an admin, open the Meta settings page in the panel, paste a Pixel ID and a Conversions API access token, map one domain event (e.g. OrderPlaced → Purchase), flip the module to test mode, and place a test order. Then check Meta Events Manager → Test Events. If a server event arrives, you have the full loop working and can expand from there.

Implementation Patterns

Configure per-environment, not per-database. The token is a secret. Store it in .env (META_CAPI_ACCESS_TOKEN, META_PIXEL_ID, META_TEST_EVENT_CODE) and have the Filament settings page display the state rather than write plaintext into the DB. If the package insists on DB storage, wrap the column in an encrypted cast in your own migration.

Deduplicate with a shared event_id. This is the single most important pattern with Meta CAPI. Generate a UUID at the point of conversion, pass it to the browser pixel (fbq('track', 'Purchase', {...}, {eventID: id})) and to the server event. Meta merges them within 48 hours. Without this you will double-count every conversion.

$eventId = (string) Str::uuid();

// browser payload
$this->dispatchBrowserEvent('fbq-track', ['event' => 'Purchase', 'eventId' => $eventId]);

// server
MetaEvent::dispatch('Purchase', $order->toTrackingPayload(), $eventId);

Dispatch through the queue. Server-side tracking is an outbound HTTP call to Graph API. Do not do it inside the checkout request. Listen to domain events, push a job, and let retries handle Meta's 5xx responses. Configure tries, backoff, and a dead-letter path so failed events are visible rather than silently dropped.

Map events in the Filament resource, not in code. The package's value proposition is that admins can add a mapping (domain event → Meta standard event → parameter mapping) without a deploy. Use that, but pin the allowed set of Meta events in config so nobody types Purchse and silently gets zero attribution.

Multi-tenancy. If you run multiple storefronts, check whether the settings table is tenant-scoped. If not, either add tenant_id yourself or run one panel per tenant. Sharing a single pixel across tenants will pollute attribution irreversibly.

Read the dispatch log resource. Server-side tracking fails quietly — Meta returns a 200 with events_received and a separate messages array containing per-event errors (invalid hashed email, event_time too old, missing action_source). Whatever log resource this package ships, make it the first place you look when conversions stop appearing.

Hashing. Meta requires SHA-256 of normalized PII: lowercase, trimmed, no punctuation on phone numbers, plus the country code. If the adapter doesn't normalize before hashing, match quality collapses. Test with a known email and compare against a manual hash('sha256', '[email protected]').

Gotchas and Tips

License is NOASSERTION. This is the single biggest blocker. There is no recognized SPDX license, which means you have no clear grant to use, modify, or redistribute it. Get written clarification from the maintainer before it goes anywhere near a commercial codebase. In a client engagement, this alone can rule the package out.

Zero stars, zero dependents, and a release date of 2026-10-27. That date is in the future relative to any sane clock — likely a tag typo, a broken CI timestamp, or a placeholder release. Treat the entire package as pre-alpha. Pin an exact version in composer.json; do not use a ^ constraint.

It is an adapter, not a module. Installing this without the underlying domain package gives you Filament pages that render but do nothing. Check composer.json require before you spend an afternoon debugging empty tables.

Filament major-version coupling. Filament moves fast and breaks plugin APIs between v3 and v4 (namespace changes, Plugin contract changes, form/table API rewrites). A package with zero dependents has not been battle-tested against your Filament version. Check the filament/filament constraint carefully, and expect to vendor-patch.

event_time must be within 7 days. If your queue backs up or a job sits in a failed state, retried events will be rejected. Cap retry windows well under a week and alert on queue lag rather than relying on retries.

action_source is required. Most "event rejected" errors from CAPI are a missing action_source (website, physical_store, system_generated) or a missing event_source_url for website events. If the adapter doesn't populate these, you will need to override the payload builder.

Access tokens. Use a System User token from Business Manager, not a personal one — personal tokens expire when the admin's password changes or they leave. Rotate on a schedule and keep the old one valid for 24h during cutover.

Cache and queue restarts. After changing any config in a Filament settings page, the package may cache the resolved config. php artisan config:clear and php artisan queue:restart after every settings change during rollout; a stale config cache sending events to the wrong pixel is a miserable debug.

Extension points to look for. Before forking, check for: a config-driven payload transformer, a binding for the event mapper contract, HasPolicies on the settings resource (you almost certainly want to restrict who can edit a live ad pixel), and a registerNavigationGroup-style hook. If none exist, the cleanest workaround is a small wrapper service that intercepts your domain events and calls the adapter's public methods, keeping your code decoupled from a package that may never get a second release.

Have a fallback. Given the maturity signals, write the Meta CAPI integration against a thin interface of your own and treat this package as one possible implementation. If it breaks, swapping in ~150 lines of Http::post('https://graph.facebook.com/v21.0/{pixel}/events', ...) should be a one-file change, not a refactor.