Laravel Server Analytics Laravel Package

Getting Started

• Install the package: composer require ohseesoftware/laravel-server-analytics
• Publish the config file: php artisan vendor:publish --tag=server-analytics-config
• Set required environment variables in .env (tracking/measurement ID, API secret if applicable, and the queue connection to use for analytics jobs)
• Review the v4 upgrade guide first — the public API changed to support queued tracking
• First use case: track a page view from a controller or route closure

use OhSeeSoftware\ServerAnalytics\Facades\Analytics;
use OhSeeSoftware\ServerAnalytics\Data\PageView;

Analytics::pageView(
    PageView::make('/pricing', 'Pricing')
);

Or dispatch the queued variant to avoid blocking the request:

use OhSeeSoftware\ServerAnalytics\Jobs\TrackPageView;

TrackPageView::dispatch('/pricing', 'Pricing');

Where to look first:

1. config/server-analytics.php — credentials, enabled flag, queue settings
2. The Analytics facade and its underlying client class
3. src/Data — request/event DTOs introduced or changed in v4
4. src/Jobs — queued tracking jobs and their serialization behaviour

Implementation Patterns

• Synchronous vs queued tracking: Use direct facade calls for low-volume or must-succeed events (e.g. a purchase confirmation). Use queued jobs for high-traffic page views and non-critical events so HTTP requests to the analytics provider never block the user response.
• Middleware-based page tracking: Register a global or route middleware that dispatches a TrackPageView job for every GET request, passing the path, title, and any server-side context (user ID, IP, user agent).
• Model event / observer tracking: Track business events from observers (UserCreated, OrderPaid) by dispatching analytics jobs after the database transaction commits.
• DTO-first workflow: Build a data object (page view, event, exception) and pass it to either the facade or a job. This keeps payloads consistent and makes serialization explicit.
• Separate analytics queue: Configure a dedicated queue connection or queue name (onQueue('analytics')) so slow analytics endpoints do not delay transactional jobs.
• After-commit dispatch: For events tied to database writes, use ->afterCommit() (Laravel 8+) on the job dispatch to avoid tracking data that was rolled back.
• Batching: If the provider supports it, batch multiple events into a single job payload to reduce HTTP overhead.
• Dependency injection: Bind the analytics client interface in a service provider and inject it into services instead of using the facade everywhere; this makes testing and swapping providers easier.
• Testing with fakes: Queue::fake() to assert jobs are dispatched, and the package’s fake (if provided) to assert payloads without hitting the network.

Gotchas and Tips

• v4 is a breaking release: The release notes explicitly state “Changes to the API to support tracking requests via a queued job.” Audit every Analytics:: call, job class, and DTO constructor after upgrading. Method names, argument order, or return types may have changed.
• Serialization of DTOs: Queued jobs serialize their payload. Ensure any data objects contain only scalar values, arrays, and serializable models — no closures, resources, or unsaved models. Test with serialize()/unserialize() locally.
• Queue retries and failures: Analytics endpoints can be flaky. Configure tries, backoff, and timeout on the job. Monitor the failed_jobs table; a failing analytics job should not mask real application errors.
• Duplicate tracking: If you migrate from synchronous calls to queued jobs, remove the old synchronous call. Running both paths will double-count events. Consider idempotency keys if the provider supports them.
• Missing client context: Server-side tracking lacks browser data. Explicitly forward IP address, user agent, and user ID in the DTO; otherwise analytics reports will show missing geo/device data.
• Config enabled flag: Disable tracking in local and testing environments via SERVER_ANALYTICS_ENABLED=false to avoid polluting production analytics.
• Queue connection quirks: If queue.connections.database.retry_after is lower than the job timeout, jobs can be retried while still running. Set retry_after appropriately or use Redis/SQS with tuned visibility timeouts.
• Testing HTTP calls: Use Http::fake() to assert the outbound analytics request payload. This catches DTO changes and provider API mismatches without network calls.
• Debugging payloads: Temporarily log the job payload and the provider response status/body. Most “missing data” issues are authentication, wrong measurement ID, or a malformed payload — not queue failures.
• Extension points: Check whether the package allows custom drivers, macros on the facade, or before/after tracking events. These are useful for adding tenant IDs, sampling, or consent-based suppression.
• Upgrade checklist: Read the full v3 → v4 diff, update DTOs and job dispatches, run the test suite with Queue::fake(), and verify one real event end-to-end in a staging environment before deploying.