Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/luketowers/laravel-ga4-event-tracking
Simplifies using the Measurement Protocol for Google Analytics 4 to track events in Laravel applications.
https://github.com/luketowers/laravel-ga4-event-tracking
ga4 google-analytics google-analytics-4 laravel measurement-protocol
Last synced: about 2 months ago
JSON representation
Simplifies using the Measurement Protocol for Google Analytics 4 to track events in Laravel applications.
- Host: GitHub
- URL: https://github.com/luketowers/laravel-ga4-event-tracking
- Owner: LukeTowers
- License: mit
- Created: 2023-12-12T20:08:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-09-19T20:49:26.000Z (3 months ago)
- Last Synced: 2024-10-12T13:10:57.232Z (2 months ago)
- Topics: ga4, google-analytics, google-analytics-4, laravel, measurement-protocol
- Language: PHP
- Homepage:
- Size: 53.7 KB
- Stars: 11
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Laravel Google Analytics 4 Measurement Protocol Event Tracking
[](https://github.com/luketowers/laravel-ga4-event-tracking/releases)
[](https://github.com/luketowers/laravel-ga4-event-tracking/actions)
[](https://packagist.org/packages/luketowers/laravel-ga4-event-tracking)
Simplifies using the [Measurement Protocol for Google Analytics 4](https://developers.google.com/analytics/devguides/collection/protocol/ga4) to track events in Laravel applications.
## Installation
1) Install package via Composer
``` bash
composer require luketowers/laravel-ga4-event-tracking
```
2) Set `GA4_MEASUREMENT_ID` and `GA4_MEASUREMENT_PROTOCOL_API_SECRET` in your .env file.
> Copy from `Google Analytics > Admin > Data Streams > [Select Site] > Measurement ID` & `Google Analytics > Admin > Data Streams > [Select Site] > Measurement Protocol API secrets` respectively.
3) Optional: Publish the config / view files by running this command in your terminal:
``` bash
php artisan vendor:publish --tag=ga4-event-tracking.config --tag=ga4-event-tracking.views
```
4) Include the `sendGA4ClientID` directive in your layout file after the Google Analytics Code tracking code.
```blade
@sendGA4ClientID
```
The [`client_id`](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#payload_post_body) is required to send an event to Google Analytics. This package provides a Blade directive which you can put in your layout file after the Google Analytics Code tracking code. It grabs the current user's GA `client_id` from either the `ga()` or `gtag()` helper functions injected by Google Analytics and makes a POST request to your application to store the `client_id` in the session, which is later used by the `DispatchAnalyticsJob` when sending events to GA4.
If you do not use this blade directive, you will have to handle retrieving, storing, and sending the `client_id` yourself. You can use `GA$::setClientId($clientId)` to set the `client_id` manually.
## Usage
This package provides two ways to send events to Google Analytics 4:
### Directly via the `GA4` facade:
Sending event directly is as simple as calling the `sendEvent($eventData)` method on the `GA4` facade from anywhere in your backend to post event to Google Analytics 4. `$eventData` contains the name and params of the event as per this [reference page](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#login). For example:
```php
GA4::sendEvent([
'name' => 'login',
'params' => [
'method' => 'Google',
],
]);
```
The `sendEvent()` method will return an array with the status of the request.
### Broadcast events to GA4 via the Laravel Event System
Just add the `ShouldBroadcastToAnalytics` interface to your event, and you're ready! You don't have to manually bind any listeners.
```php
order = $order;
}
}
```
There are additional methods that let you customize the call sent to GA4.
#### `broadcastGA4EventAs`
With this method you can customize the name of the [Event Action](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventAction). By default, we use the class name with the class's namespace removed. This method gives you access to the underlying `GA4` class instance as well.
#### `eventOccurredAt`
With this method you can customize the time that the event occurred at. This will be used in the `timestamp_micros` parameter sent to the Measurement Protocol. By default, we use the current time. You must return an instance of `Carbon\Carbon` in order for it to be used.
```php
use Carbon\Carbon;
use LukeTowers\GA4EventTracking\GA4;
use LukeTowers\GA4EventTracking\ShouldBroadcastToAnalytics;
use Illuminate\Queue\SerializesModels;
class OrderSubmitted extends Event implements ShouldBroadcastToAnalytics
{
use SerializesModels;
protected Carbon $submittedAt;
public function __construct(
public Order $order
) {
$this->submittedAt = now();
}
public function eventOccurredAt(): Carbon
{
return $this->submittedAt;
}
}
```
#### `withGA4Parameters`
With this method you can set the parameters of the event being sent.
```php
order = $order;
}
public function withGA4Parameters(GA4 $ga4): array
{
$eventData = [
'transaction_id' => $order->id,
'value' => $order->amount_total,
'currency' => 'USD',
'tax' => $order->amount_tax,
'shipping' => $order->amount_shipping,
'items' => [],
'event_category' => config('app.name'),
'event_label' => 'Order Created',
];
foreach ($order->items as $item) {
$eventData['items'][] = [
'id' => $item->sku ?: 'p-' . $item->product->id,
'name' => $item->title,
'brand' => $item->product->brand->name ?? '',
'category' => $item->product->category->title ?? '',
'quantity' => $item->quantity,
'price' => $item->price,
'variant' => $item->variant->title ?? '',
];
}
return $eventData;
}
public function broadcastGA4EventAs(GA4 $ga4): string
{
return 'purchase';
}
}
```
### 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
[
SendEmailVerificationNotification::class,
DispatchAnalyticsJob::class,
],
];
}
```
### Debugging Mode
You can also enable [debugging mode](https://developers.google.com/analytics/devguides/collection/protocol/ga4/validating-events) by calling `enableDebugging()` method before calling the `sendEvent()` method. Like so - `GA4::enableDebugging()->sendEvent($eventData)`. The `sendEvent()` method will return the response (array) from Google Analytics request in that case.
## Testing
``` bash
composer test
```
or
``` bash
./vendor/bin/phpunit
```
## Security
If you discover any security related issues, please use the [Report a vulnerability](https://github.com/luketowers/laravel-ga4-event-tracking/security/advisories/new) button instead of using the issue tracker.
## Credits:
This package is a fork of the following projects:
- [protonemedia/laravel-analytics-event-tracking](https://github.com/protonemedia/laravel-analytics-event-tracking): Original package, but only supports Universal Analytics.
- [daikazu/laravel-ga4-event-tracking](https://github.com/daikazu/laravel-ga4-event-tracking): Forked from the original package to support Google Analytics 4 but the package was not maintained and it was not compatible with Laravel 10.
- [accexs/laravel-ga4-event-tracking](https://github.com/accexs/laravel-ga4-event-tracking): Forked from `daikazu`'s package but was missing some features and was not cleanly forked.
## License
This package is open-sourced software licensed under the [MIT License](LICENSE).