Analytics Meta Laravel Package

Getting Started

This is a niche, low-adoption package (0 stars, no dependents), so treat the README as a starting point and confirm class names against src/ before trusting any snippet.

1. Install and publish

   composer require liberusoftware/analytics-meta
   php artisan vendor:publish --tag=analytics-meta-config
   

2. Configure credentials in .env — you'll typically need a Meta Pixel/Dataset ID and a Conversions API access token. Because the package advertises "protected configuration," expect secrets to be read through config or a dedicated config repository rather than being freely dumped; check config/analytics-meta.php for which keys are marked protected and whether they're encrypted at rest.

3. Wire up consent. The headline feature is consent-aware sending. Find the consent contract/resolver the package expects (likely a bound interface or a config-driven callback) and point it at your existing consent solution (Cookiebot, Osano, a custom ConsentService, etc.). Nothing should send until this is resolved.

4. First use case — map one server event. Pick a single high-value conversion (e.g. OrderPlaced → Meta Purchase) and register the mapping. Then run the diagnostics command (something like php artisan analytics-meta:diagnostics) to confirm the pixel ID, token, and mapping are recognized before you touch the browser side.

Where to look first: config/analytics-meta.php (event map, consent binding, dedup settings), the mapping/normalization classes under src/, and the diagnostics command. The diagnostics output is your fastest signal on whether the package is wired correctly.

Implementation Patterns

Config-driven event mapping. Most packages of this shape let you map Laravel/domain events to Meta standard events in config. Keep the map declarative and thin — one entry per domain event, with the Meta event name and a payload transformer. Resist putting business logic in the map; resolve it in the event or a listener.

Shared event_id for browser/server deduplication. The dedup feature only works if the browser Pixel and the server-side Conversions API call carry the same event_id. Generate it once (UUID) at the point of the user action, stash it on the event/model, render it into the Blade pixel call, and pass the identical string to the server-side sender. If your frontend fires the pixel separately, make the ID a first-class part of your event payload, not an afterthought.

Consent gate at send time, not dispatch time. The correct pattern is: dispatch your domain event normally, then let the package's consent check decide whether to emit. If you're queueing, ensure the consent check runs inside the job (or the job re-validates) so a consent withdrawal between dispatch and execution doesn't leak an event.

Hashing via the package's normalizer. Meta requires SHA-256 hashed, normalized PII (lowercased/trimmed email, E.164 phone). Pass raw user data to the package's normalizer/hasher and let it do the work. Hand-rolling hash('sha256', $email) in your listener is how you end up with double-hashed or un-normalized values that silently fail to match.

Queue the server-side call. Conversions API calls are outbound HTTP; wrap them in a queued job with retries and a timeout. Keep them off the request path, especially on checkout flows.

Testing pattern. Bind a fake transport/client in tests and assert the outgoing payload — event name, event_id, hashed user data, consent state. This is the only reliable way to catch dedup and hashing regressions, since Meta's UI won't tell you why a match failed.

Diagnostics as a smoke test. Run the diagnostics command in CI (staging) after config changes, and keep its output in your deploy logs for the first few weeks.

Gotchas and Tips

• Double hashing is the #1 silent failure. If Meta's Event Match Quality is poor despite correct-looking code, check whether email/phone are being hashed twice — once by you, once by the package.
• event_id must be byte-identical. Trailing whitespace, different UUID formats, or a regenerated ID between browser and server breaks dedup. Dedup only reconciles events with matching names and IDs, within Meta's ~48h window.
• Config caching bites. After publishing or changing config, run php artisan config:clear (and in production, config:cache during deploy). "Protected" config values may not behave the same cached vs. uncached — verify both paths.
• Test vs. live events. Use a test event code (test_event_code) when validating in Events Manager; forgetting to remove it means real conversions never register.
• Consent withdrawal after queueing. A job dispatched with consent can still run after the user opts out. Add a re-check inside the job, or drop the job on withdrawal.
• Sparse docs, low adoption. With 0 stars and no dependents, expect thin documentation and unannounced API churn between releases (last release listed as 2026-10-27 — pin the version in composer.json and read the CHANGELOG/source on upgrade). Don't assume the public API is stable.
• Extension points to prefer: custom event mappers/transformers, a custom normalizer, and swapping the consent resolver binding — these are usually the intended seams. Avoid subclassing internals or editing vendor code.
• Debugging: log the serialized payload (with PII redacted) at the transport boundary, and cross-check Events Manager's "Deduplication" and "Event Match Quality" panels. The diagnostics command should surface token validity, pixel/dataset ID mismatch, and recent send status — start there before adding your own logging.