PHPackages schenke-io/laravel-ga4-marketing - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. schenke-io/laravel-ga4-marketing ActiveLibrary[API Development](/categories/api) schenke-io/laravel-ga4-marketing ================================ GA4 Marketing integration for Laravel v0.1.4(1w ago)0101↓25%MITPHPPHP ^8.3CI passing Since Apr 21Pushed 1w agoCompare [ Source](https://github.com/schenke-io/laravel-ga4-marketing)[ Packagist](https://packagist.org/packages/schenke-io/laravel-ga4-marketing)[ RSS](/packages/schenke-io-laravel-ga4-marketing/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (15)Versions (6)Used By (0) [![Version](https://camo.githubusercontent.com/80de2b7a184c5776de98201bf1e42f00a20f986b661837d53d1d247da69b44bf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736368656e6b652d696f2f6c61726176656c2d6761342d6d61726b6574696e673f7374796c653d666c6174)](https://packagist.org/packages/schenke-io/laravel-ga4-marketing)[![Downloads](https://camo.githubusercontent.com/8a936f03d0d5894e641e5e61835fc67c30cd90a9d81ff63366f9d0af82173fc8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736368656e6b652d696f2f6c61726176656c2d6761342d6d61726b6574696e673f7374796c653d666c6174)](https://packagist.org/packages/schenke-io/laravel-ga4-marketing)[![Tests](https://github.com/schenke-io/laravel-ga4-marketing/actions/workflows/run-tests.yml/badge.svg)](https://github.com/schenke-io/laravel-ga4-marketing/actions/workflows/run-tests.yml)[![License](https://camo.githubusercontent.com/c00ec734e661982aea8de0c9d0454a28adbd820455f9c132123c2ed089b9d424/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736368656e6b652d696f2f6c61726176656c2d6761342d6d61726b6574696e673f7374796c653d666c6174)](https://github.com/schenke-io/laravel-ga4-marketing/blob/main/LICENSE.md)[![PHP](https://camo.githubusercontent.com/113a32ee02b75de971e01864a120863071915df1f72faf6bcc50ad862568a0e9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f736368656e6b652d696f2f6c61726176656c2d6761342d6d61726b6574696e673f7374796c653d666c6174)](https://packagist.org/packages/schenke-io/laravel-ga4-marketing) Laravel GA4 Marketing ====================================================================== [](#laravel-ga4-marketing) [![Coverage](https://camo.githubusercontent.com/0c967d746eb7f4fe28065a3b94d23faa207cd6f4a968535b20fce0310a87cf89/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d677265656e)](https://camo.githubusercontent.com/0c967d746eb7f4fe28065a3b94d23faa207cd6f4a968535b20fce0310a87cf89/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d677265656e)[![PHPStan Level](https://camo.githubusercontent.com/ff3c7f8c8667ce643f47e74532748f673482a5f95d7d4269f925f2eebbe5117e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e)](https://camo.githubusercontent.com/ff3c7f8c8667ce643f47e74532748f673482a5f95d7d4269f925f2eebbe5117e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e) This package provides a simple way to integrate Google Analytics 4 (GA4) event tracking into your Laravel application. It includes middleware for automatic page view tracking and a service to send custom events directly to GA4. Features -------------------------------------------- [](#features) - **Cookie-based Tracking**: Persistent visitor identification using a `visitor` cookie (default 100 days). - **Privacy-first Hashing**: Securely generate hashed User IDs for authenticated users, which automatically overwrite the anonymous visitor cookie. - **Hybrid Event Handling**: Support for both immediate API calls and queued background jobs for event processing. - **JS-Triggered Tracking**: Client-side triggers for events, reducing server-side overhead and improving accuracy. - **Automatic Tracking**: Easy integration via Blade directives (`@Ga4MarketingScript` or `@Ga4MarketingConfig`) for automatic page view and engagement tracking. - **Bot Filtering**: Built-in filtering to prevent common bots and crawlers from polluting your analytics. - **Visibility Tracking**: Blade component to track when elements become visible using IntersectionObserver. - **Non-blocking Execution**: Events are sent with a short timeout and exceptions are caught to ensure your application remains responsive. - [Laravel GA4 Marketing](#laravel-ga4-marketing) - [Features](#features) - [Installation](#installation) - [Client-Side Setup](#client-side-setup) - [Configuration](#configuration) - [Advanced Configuration](#advanced-configuration) - [Usage](#usage) - [1. Standard Mode (Quick Setup)](#1-standard-mode-quick-setup) - [2. Advanced Mode (Vite & Bundling)](#2-advanced-mode-vite-bundling) - [3. Server-Side Only Mode](#3-server-side-only-mode) - [Automatic Page View Tracking](#automatic-page-view-tracking) - [Disabling Automatic Page Views](#disabling-automatic-page-views) - [Visitor & User Identification](#visitor-user-identification) - [Google Ads Attribution](#google-ads-attribution) - [Server-side Tracking Middlewares](#server-side-tracking-middlewares) - [Page View Tracking](#page-view-tracking) - [Outbound Link Tracking](#outbound-link-tracking) - [Sending Custom Events](#sending-custom-events) - [Recommended Events](#recommended-events) - [Bot Filtering](#bot-filtering) - [Livewire Event Bridging](#livewire-event-bridging) - [JavaScript Event Bridging](#javascript-event-bridging) - [Visibility Tracking](#visibility-tracking) - [Declarative Tracking](#declarative-tracking) - [Click Tracking](#click-tracking) - [Outbound Link Tracking](#outbound-link-tracking) - [Custom Click Events](#custom-click-events) - [Automatic Parameter Extraction](#automatic-parameter-extraction) - [User Engagement Tracking](#user-engagement-tracking) - [User ID Tracking](#user-id-tracking) - [Event Validation (Debug Mode)](#event-validation-debug-mode) - [Connection Verification](#connection-verification) Installation ---------------------------------------------------- [](#installation) You can install the package via composer: ``` composer require schenke-io/laravel-ga4-marketing ``` You should publish the config file with: ``` php artisan vendor:publish --tag="ga4-marketing-config" ``` ### Client-Side Setup [](#client-side-setup) To enable automatic page view tracking and declarative event tracking (clicks, visibility), add the following Blade directive to your main layout file (e.g., `resources/views/layouts/app.blade.php`), typically before the closing `` tag: ``` @Ga4MarketingScript ``` ### Configuration [](#configuration) Set up your Google Analytics 4 credentials in your `.env` file: ``` GA4_MEASUREMENT_ID=G-XXXXXXXXXX GA4_API_SECRET=your-api-secret ``` You can find these values in your Google Analytics Admin panel under **Data Streams > \[Your Stream\] > Measurement Protocol API secrets**. #### Advanced Configuration [](#advanced-configuration) The `config/ga4-marketing.php` file allows you to customize several aspects of the package: ``` return [ /* * Full path to the service account credentials JSON file. * This is required for server-to-server authentication. */ 'credentials' => env('GOOGLE_MARKETING_CREDENTIALS'), 'ga4' => [ /* * Your Google Analytics 4 Measurement ID (e.g., G-XXXXXXXXXX). * Found in GA4 Admin > Data Streams > [Your Stream]. */ 'measurement_id' => env('GA4_MEASUREMENT_ID', config('services.google.ga4.measurement_id')), /* * The Measurement Protocol API Secret. * Created in GA4 Admin > Data Streams > [Your Stream] > Measurement Protocol API secrets. */ 'api_secret' => env('GA4_API_SECRET', config('services.google.ga4.api_secret')), /* * When enabled, events include 'debug_mode=1', making them * instantly visible in the GA4 DebugView for troubleshooting. */ 'debug_mode' => env('GA4_DEBUG_MODE', false), /* * A string used to salt the hash when generating anonymous Client IDs. * Changing this will reset the identity of returning anonymous users. */ 'client_id_salt' => env('GA4_CLIENT_ID_SALT', ''), 'rate_limit' => [ /* * Enable or disable server-side rate limiting per client * to prevent API abuse or excessive event tracking. */ 'enabled' => env('GA4_RATE_LIMIT_ENABLED', true), /* * The maximum number of events allowed per client within * the specified decay period. */ 'max_attempts' => env('GA4_RATE_LIMIT_MAX_ATTEMPTS', 30), /* * The time window (in seconds) for rate limiting. After this period, * the attempt count for a client is reset. */ 'decay_seconds' => env('GA4_RATE_LIMIT_DECAY_SECONDS', 60), ], /* * The duration (in seconds) of inactivity before a new session is started. * Defaults to 1800 seconds (30 minutes). */ 'session_lifetime' => env('GA4_SESSION_LIFETIME', 1800), /* * How events are processed: 'api' for immediate sending or 'job' to * queue them for background processing. */ 'event_handling' => env('GA4_EVENT_HANDLING', 'api'), /* * When enabled, the client ID is automatically set to a hashed * version of the authenticated user's ID. */ 'client_from_user_id' => env('GA4_CLIENT_FROM_USER_ID', false), /* * The name of the cookie used to store the visitor ID. */ 'cookie_name' => env('GA4_COOKIE_NAME', 'visitor'), /* * The lifetime of the visitor cookie in minutes (144000 = 100 days). */ 'cookie_lifetime' => env('GA4_COOKIE_LIFETIME', 144000), ], /* * Add additional bot user-agent fragments here to be excluded from tracking. * Useful for filtering out custom crawlers or internal monitoring tools. */ 'extra_bots' => [ // 'custom-bot', ], ]; ``` Usage -------------------------------------- [](#usage) This package supports three primary integration modes to suit different application architectures. ### 1. Standard Mode (Quick Setup) [](#1-standard-mode-quick-setup) Best for most applications. Simply add the `@Ga4MarketingScript` directive to your main layout file, typically before the closing `` tag: ``` @Ga4MarketingScript ``` This directive: - Renders the necessary tracking scripts. - Automatically handles CSRF tokens and event routing. - Sends a `page_view` event on window load. - Enables declarative tracking (clicks, visibility). - Ensures scripts are only included once per page. ### 2. Advanced Mode (Vite & Bundling) [](#2-advanced-mode-vite--bundling) If you prefer to bundle the tracking logic with your application for better performance, you can import the tracker from the package resources and use the configuration directive. **JavaScript Setup:**Import the tracker in your `resources/js/app.js`: ``` import '../../vendor/schenke-io/laravel-ga4-marketing/resources/js/ga4-tracker'; ``` **Blade Setup:**Add the `@Ga4MarketingConfig` directive in your layout. This provides the necessary configuration (route, CSRF token) to the bundled script: ``` @Ga4MarketingConfig ``` The `@Ga4MarketingConfig` directive is smart: it automatically disables the client-side `page_view` event if the page view was already tracked on the server (e.g., via middleware), preventing double counting. ### 3. Server-Side Only Mode [](#3-server-side-only-mode) For tracking without any client-side scripts, you can rely entirely on the `track-page-view` middleware and the `AnalyticsService`. ``` Route::middleware(['track-page-view'])->group(function () { // your routes }); ``` ### Automatic Page View Tracking [](#automatic-page-view-tracking) When using `@Ga4MarketingScript` or `@Ga4MarketingConfig`, a `page_view` event is automatically sent to GA4 on window load, unless: 1. It was already tracked on the server during the same request. 2. It is explicitly disabled via the `` tag. #### Disabling Automatic Page Views [](#disabling-automatic-page-views) If you want to disable automatic tracking for a specific page while still keeping other tracking features active, add `data-ga4-event="no-pageview"` (or the shorthand `data-ga4="no-pageview"`) to the `` tag: ``` ``` ### Visitor & User Identification [](#visitor--user-identification) The package uses a `visitor` cookie (configurable) to maintain a persistent client ID for anonymous users. This cookie is set to last 100 days by default and is automatically extended on each request. If a user is authenticated and `client_from_user_id` is enabled in the config, the package will: 1. Generate a hashed version of the User ID. 2. Use this hash as the GA4 `client_id`. 3. Overwrite the `visitor` cookie with this hashed ID. This ensures that the same user is tracked consistently across different devices if they log in, while maintaining privacy by hashing the actual database ID. ### Google Ads Attribution [](#google-ads-attribution) To capture Google Ad IDs (`gclid`, `wbraid`, `gbraid`) from the URL and store them in the server-side cache, add the `capture-ad-parameters` middleware to your routes. This is recommended to be used alongside page view tracking: ``` Route::middleware(['capture-ad-parameters'])->group(function () { // your routes }); ``` The captured IDs are automatically included in all subsequent events sent via `AnalyticsService`. ### Server-side Tracking Middlewares [](#server-side-tracking-middlewares) The package provides optional middlewares for server-side tracking. #### Page View Tracking [](#page-view-tracking) To track page views on the server-side, add the `track-page-view` middleware. This is useful when you want to ensure page views are tracked even if JavaScript is disabled or blocked. ``` Route::middleware(['track-page-view'])->group(function () { // your routes }); ``` #### Outbound Link Tracking [](#outbound-link-tracking) To track outbound links that go through a redirect in your application, use the `track-outbound-link` middleware. It automatically sends a `click` event with `outbound: true` when a `RedirectResponse` to an external domain is detected. ``` Route::middleware(['track-outbound-link'])->group(function () { Route::get('/external-redirect', function () { return redirect('https://external-site.com'); }); }); ``` ### Sending Custom Events [](#sending-custom-events) You can also use the `AnalyticsService` to send custom events manually: ``` use SchenkeIo\LaravelGa4Marketing\Services\AnalyticsService; public function someAction(AnalyticsService $ga4Service) { $clientId = $ga4Service->getClientId(); $ga4Service->sendEvent($clientId, 'button_click', [ 'button_name' => 'subscribe', 'location' => 'footer' ]); } ``` ### Recommended Events [](#recommended-events) The `AnalyticsService` provides helper methods for standard GA4 events using camelCase naming: ``` // E-commerce events $ga4Service->viewItem($items, 'USD', 10.0); $ga4Service->addToCart($items, 'USD', 10.0); $ga4Service->beginCheckout($items, 'USD', 10.0, 'COUPON'); $ga4Service->purchase($transactionId, $items, 99.99, 'USD'); // Other recommended events $ga4Service->login('google'); $ga4Service->signUp('email'); $ga4Service->search('query'); $ga4Service->share('social', 'article', '123'); $ga4Service->scroll(90); $ga4Service->fileDownload('report.pdf', 'pdf', 'https://example.com/report.pdf'); $ga4Service->calculatorUsed(['type' => 'mortgage']); ``` ### Bot Filtering [](#bot-filtering) The package automatically filters out common bots to keep your analytics clean. You can extend the built-in bot blacklist in `config/ga4-marketing.php`: ``` 'extra_bots' => [ 'custom-bot-fragment', // ... add more as needed ], ``` ### Livewire Event Bridging [](#livewire-event-bridging) You can automatically bridge Livewire events to GA4 by dispatching a `ga4-event` from your Livewire component. The package intercepts this and dispatches a browser event (`ga4-event-triggered`), which is then sent to GA4 by the client-side tracker. ``` $this->dispatch('ga4-event', 'button_click', [ 'button_name' => 'subscribe' ]); ``` ### JavaScript Event Bridging [](#javascript-event-bridging) To send events from JavaScript, you can use the `window.ga4Event` helper: ``` ga4Event('js_button_click', { source: 'home_banner' }); ``` ### Visibility Tracking [](#visibility-tracking) #### Declarative Tracking [](#declarative-tracking) The easiest way to track visibility is by adding `data-ga4-event="scroll"` (or `data-ga4="scroll"`) to any element. You can specify the area name using `data-ga4-area`: ``` ``` This sends a `scroll` event with the `visible_area` parameter when the element becomes visible in the viewport. ### Click Tracking [](#click-tracking) You can automatically track clicks on any element using declarative data attributes. #### Outbound Link Tracking [](#outbound-link-tracking-1) To track clicks to external domains, use `data-ga4-event="outbound"` (or `data-ga4="outbound"`) on an `` tag: ``` External Link ``` This automatically sets the event name to `click`, sets `outbound: true`, and extracts `link_url` and `link_domain`. #### Custom Click Events [](#custom-click-events) Use `data-ga4-event` (or `data-ga4`) for the event name and `data-ga4-params` for optional parameters (as a JSON string): ``` Sign Up ``` #### Automatic Parameter Extraction [](#automatic-parameter-extraction) When you use tracking on an `` tag, the package automatically captures: ParameterSourceDescription`link_url``href`The destination URL of the link.`link_text``innerText`The visible text inside the link.`link_id``id`The ID attribute of the element.`link_classes``className`The CSS classes applied to the link.`link_domain``href`The hostname (for outbound links).### User Engagement Tracking [](#user-engagement-tracking) The tracker automatically tracks the time a user spends on a page and sends a `user_engagement` event (with `engagement_time_msec`) when the user navigates away or closes the tab. This requires `@Ga4MarketingScript` to be present. ### User ID Tracking [](#user-id-tracking) To track a specific user across sessions, you can set the User ID in the `AnalyticsService`: ``` $ga4Service->setUserId('user-123'); ``` Once set, the `user_id` will be included in all subsequent events sent during the current request. ### Event Validation (Debug Mode) [](#event-validation-debug-mode) You can enable debug mode on the `AnalyticsService` to send events to the GA4 validation endpoint instead of the live collection endpoint. This is useful for testing your integration without affecting live data: ``` $response = $ga4Service->setDebugMode(true) ->sendEvent($clientId, 'test_event', ['value' => 123]); if ($response && $response->successful()) { $debugInfo = $response->json(); // inspect validationMessages } ``` When `setDebugMode(true)` is called: 1. The event is sent to the GA4 **debug validation endpoint**. 2. The `debug_mode: 1` parameter is automatically added to all events. 3. The `sendEvent` method returns the `Response` object containing GA4 validation messages. ### Connection Verification [](#connection-verification) You can verify your GA4 configuration using the built-in console command. This command sends a test event to the Google Analytics debug validation server and reports any issues: ``` php artisan ga4-marketing:verify-ga4 ``` --- Markdown file generated by [schenke-io/packaging-tools](https://github.com/schenke-io/packaging-tools) ### Health Score 42 — FairBetter than 88% of packages Maintenance98 Actively maintained with recent releases Popularity13 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Total 5 Last Release 13d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/111449674?v=4)[Kay-Uwe Schenke](/maintainers/schenke-io)[@schenke-io](https://github.com/schenke-io) --- Top Contributors [![schenke-io](https://avatars.githubusercontent.com/u/111449674?v=4)](https://github.com/schenke-io "schenke-io (7 commits)") ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/schenke-io-laravel-ga4-marketing/health.svg) ``` [![Health](https://phpackages.com/badges/schenke-io-laravel-ga4-marketing/health.svg)](https://phpackages.com/packages/schenke-io-laravel-ga4-marketing) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 76318.2M110](/packages/laravel-mcp)[defstudio/telegraph A laravel facade to interact with Telegram Bots 815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client)[api-platform/laravel API Platform support for Laravel 59156.3k10](/packages/api-platform-laravel)[ralphjsmit/laravel-glide Auto-magically generate responsive images from static image files. 4923.6k5](/packages/ralphjsmit-laravel-glide) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)