protonemedia / laravel-analytics-event-tracking
Laravel package to easily send events to Google Analytics
Fund package maintenance!
pascalbaljet
Installs: 152 700
Dependents: 0
Suggesters: 0
Security: 0
Stars: 243
Watchers: 8
Forks: 23
Open Issues: 3
Requires
- php: ^8.1 || ^8.2
- illuminate/bus: ^9.0 || ^10.0
- illuminate/http: ^9.0 || ^10.0
- illuminate/queue: ^9.0 || ^10.0
- illuminate/validation: ^9.0 || ^10.0
- theiconic/php-ga-measurement-protocol: ^2.7
Requires (Dev)
- mockery/mockery: ^1.4.4
- nesbot/carbon: ^2.66
- orchestra/testbench: ^7.0 || ^8.0
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2024-01-09 10:49:41 UTC
README
⚠️ This package is unmaintained and doesn't work with GA4.
Laravel Analytics Event Tracking
https://twitter.com/pascalbaljet/status/1257926601339277312
Laravel package to easily send events to Google Analytics
Sponsor this package!
❤️ We proudly support the community by developing Laravel packages and giving them away for free. If this package saves you time or if you're relying on it professionally, please consider sponsoring the maintenance and development. Keeping track of issues and pull requests takes time, but we're happy to help!
Laravel Splade
Did you hear about Laravel Splade? 🤩
It's the magic of Inertia.js with the simplicity of Blade. Splade provides a super easy way to build Single Page Applications using Blade templates. Besides that magic SPA-feeling, it comes with more than ten components to sparkle your app and make it interactive, all without ever leaving Blade.
Features
- Use Laravel Events to track events with GA.
- Blade Directive to easily store the Client ID.
- Full access to the underlying library.
- API calls to GA are queued.
- Easy to configure.
- Compatible with Laravel 9.0.
- PHP 8.0 or higher required.
Installation
You can install the package via composer:
composer require protonemedia/laravel-analytics-event-tracking
Configuration
Publish the config and view files:
php artisan vendor:publish --provider="ProtoneMedia\AnalyticsEventTracking\ServiceProvider"
Set your Google Analytics Tracking ID in the .env
file or in the config/analytics-event-tracking.php
file.
GOOGLE_ANALYTICS_TRACKING_ID=UA-01234567-89
This package supports Google Analytics 4 as of version 1.2.1. Please republish the view file if you're upgrading to a new Google Analytics 4 property.
Blade Directive
This package comes with a @sendAnalyticsClientId
directive that sends the Client ID from the GA front-end to your Laravel backend and stores it in the session.
It uses the Axios HTTP library the make an asynchronous POST request. Axios was choosen because it is provided by default in Laravel in the resources/js/bootstrap.js
file.
Add the directive somewhere after initializing/configuring GA. The POST request will only be made if the Client ID
isn't stored yet or when it's refreshed.
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-01234567-89"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-01234567-89', { 'send_page_view': false }); gtag('event', 'page_view', { 'event_callback': function() { @sendAnalyticsClientId }}); </script>
If you don't use Axios, you have to implement this call by yourself. By default the endpoint is /gaid
but you can customize it in the configuration file. The request is handled by the ProtoneMedia\AnalyticsEventTracking\Http\StoreClientIdInSession
class. Make sure to also send the CSRF token.
Broadcast events to Google Analytics
Add the ShouldBroadcastToAnalytics
interface to your event and you're ready! You don't have to manually bind any listeners.
<?php namespace App\Events; use App\Order; use Illuminate\Foundation\Events\Dispatchable; use Illuminate\Queue\SerializesModels; use ProtoneMedia\AnalyticsEventTracking\ShouldBroadcastToAnalytics; class OrderWasCreated implements ShouldBroadcastToAnalytics { use Dispatchable, SerializesModels; public $order; public function __construct(Order $order) { $this->order = $order; } }
Handle framework and 3rd-party events
If you want to handle events where you can't add the ShouldBroadcastToAnalytics
interface, you can manually register them in your EventServiceProvider
using the DispatchAnalyticsJob
listener.
<?php namespace App\Providers; use Illuminate\Auth\Events\Registered; use Illuminate\Auth\Listeners\SendEmailVerificationNotification; use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider; use ProtoneMedia\AnalyticsEventTracking\Listeners\DispatchAnalyticsJob; class EventServiceProvider extends ServiceProvider { /** * The event listener mappings for the application. * * @var array */ protected $listen = [ Registered::class => [ SendEmailVerificationNotification::class, DispatchAnalyticsJob::class, ], ]; }
Customize the broadcast
There are two additional methods that lets you customize the call to Google Analytics.
With the withAnalytics
method you can interact with the underlying package to set additional parameters. Take a look at the TheIconic\Tracking\GoogleAnalytics\Analytics
class to see the available methods.
With the broadcastAnalyticsActionAs
method you can customize the name of the Event Action. By default we use the class name with the class's namespace removed. This method gives you access to the underlying Analytics
class as well.
<?php namespace App\Events; use App\Order; use TheIconic\Tracking\GoogleAnalytics\Analytics; use Illuminate\Foundation\Events\Dispatchable; use Illuminate\Queue\SerializesModels; use ProtoneMedia\AnalyticsEventTracking\ShouldBroadcastToAnalytics; class OrderWasCreated implements ShouldBroadcastToAnalytics { use Dispatchable, SerializesModels; public $order; public function __construct(Order $order) { $this->order = $order; } public function withAnalytics(Analytics $analytics) { $analytics->setEventValue($this->order->sum_in_cents / 100); } public function broadcastAnalyticsActionAs(Analytics $analytics) { return 'CustomEventAction'; } }
Handling the Client ID outside a HTTP Request
You might want to track an event that occurs outside of a HTTP Request, for example in a queued job or while handling a 3rd-party callback/webhook. Let's continue with the Order
example. When the Order
is created, you could save the Client ID
in the database.
<?php namespace App\Http\Controllers; use App\Order; use App\Http\Requests\CreateOrderRequest; use ProtoneMedia\AnalyticsEventTracking\Http\ClientIdRepository; class CreateOrderController { public function __invoke(CreateOrderRequest $request, ClientIdRepository $clientId) { $attributes = $request->validated(); $attributes['google_analytics_client_id'] = $clientId->get(); return Order::create($attributes); } }
When you receive a webhook from your payment provider and you dispatch an OrderWasPaid
event, you can use the withAnalytics
method in your event to reuse the google_analytics_client_id
:
<?php namespace App\Events; use App\Order; use TheIconic\Tracking\GoogleAnalytics\Analytics; use Illuminate\Foundation\Events\Dispatchable; use Illuminate\Queue\SerializesModels; use ProtoneMedia\AnalyticsEventTracking\ShouldBroadcastToAnalytics; class OrderWasPaid implements ShouldBroadcastToAnalytics { use Dispatchable, SerializesModels; public $order; public function __construct(Order $order) { $this->order = $order; } public function withAnalytics(Analytics $analytics) { $analytics->setClientId($this->order->google_analytics_client_id); } }
Additional configuration
You can configure some additional settings in the config/analytics-event-tracking.php
file:
use_ssl
: Use SSL to make calls to GAis_enabled
: Set tofalse
to prevent events from being sent to GAanonymize_ip
: Anonymizes the last digits of the user's IPsend_user_id
: Send the ID of the authenticated user to GAqueue_name
: Specify a queue to perform the calls to GAclient_id_session_key
: The session key to store the Client IDhttp_uri
: HTTP URI to post the Client ID to (from the Blade Directive)
Testing
composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Other Laravel packages
Laravel Blade On Demand
: Laravel package to compile Blade templates in memory.Laravel Cross Eloquent Search
: Laravel package to search through multiple Eloquent models.Laravel Eloquent Scope as Select
: Stop duplicating your Eloquent query scopes and constraints in PHP. This package lets you re-use your query scopes and constraints by adding them as a subquery.Laravel Eloquent Where Not
: This Laravel package allows you to flip/invert an Eloquent scope, or really any query constraint.Laravel FFMpeg
: This package provides an integration with FFmpeg for Laravel. The storage of the files is handled by Laravel's Filesystem.Laravel Form Components
: Blade components to rapidly build forms with Tailwind CSS Custom Forms and Bootstrap 4. Supports validation, model binding, default values, translations, includes default vendor styling and fully customizable!Laravel Mixins
: A collection of Laravel goodies.Laravel Paddle
: Paddle.com API integration for Laravel with support for webhooks/events.Laravel Verify New Email
: This package adds support for verifying new email addresses: when a user updates its email address, it won't replace the old one until the new one is verified.Laravel WebDAV
: WebDAV driver for Laravel's Filesystem.
Security
If you discover any security related issues, please email pascal@protone.media instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
Treeware
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.