README

Laravel GA4 Marketing

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

• 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.
• Page View Component: Simple Blade component to manually track page views including page location, title, and visitor language.
• 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
  • Features
  • Installation
    • Client-Side Setup
    • Configuration
      • Advanced Configuration
  • Usage
    • JavaScript Tracking Initialization
    • Automatic Page View Tracking
      • Disabling Automatic Page Views
    • Visitor & User Identification
    • Google Ads Attribution
    • Server-side Tracking Middlewares
      • Page View Tracking
      • Outbound Link Tracking
    • Sending Custom Events
    • Recommended Events
    • Bot Filtering
    • Livewire Event Bridging
    • JavaScript Event Bridging
      • Vite & Bundling
    • Visibility Tracking
      • Declarative Tracking
    • Click Tracking
      • Outbound Link Tracking
      • Custom Click Events
      • Automatic Parameter Extraction
    • User Engagement Tracking
    • User ID Tracking
    • Event Validation (Debug Mode)
    • Connection Verification

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

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 </body> tag:

@Ga4MarketingScript

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

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

JavaScript Tracking Initialization

To enable client-side tracking, include the following Blade directive in your main layout (usually before the closing </body> tag):

@Ga4MarketingScript

This directive replaces the legacy <x-ga4-marketing::ga4-marketing /> component. It renders the necessary tracking scripts and handles automatic events. It ensures scripts are only included once per page.

Automatic Page View Tracking

When @Ga4MarketingScript is included, a page_view event is automatically sent to GA4 on window load.

Disabling Automatic Page Views

If you want to disable automatic tracking for a specific page, add data-ga4-event="no-pageview" to the <body> tag:

<body data-ga4-event="no-pageview">

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

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

The package provides optional middlewares for server-side 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

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

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

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

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

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

To send events from JavaScript, first include the tracking script in your layout using the Blade directive:

@Ga4MarketingScript

This directive renders the tracking scripts and ensures they are only included once. You can then use the window.ga4Event helper:

ga4Event('js_button_click', {
    source: 'home_banner'
});

Vite & Bundling

If you prefer to bundle the tracking logic with your application, you can import the tracker from the package resources:

import { ga4Event } from '../../vendor/schenke-io/laravel-ga4-marketing/resources/js/ga4-tracker';

ga4Event('custom_event', { key: 'value' });

Visibility Tracking

Declarative Tracking

The easiest way to track visibility is by adding data-ga4-event="scroll" to any element. You can specify the area name using data-ga4-area:

<div data-ga4-event="scroll" data-ga4-area="pricing_table">
    <!-- content -->
</div>

This sends a scroll event with the visible_area parameter when the element becomes visible in the viewport.

Click Tracking

You can automatically track clicks on any element using declarative data attributes.

Outbound Link Tracking

To track clicks to external domains, use data-ga4-event="outbound" on an <a> tag:

<a href="https://example.com" data-ga4-event="outbound">External Link</a>

This automatically sets the event name to click, sets outbound: true, and extracts link_url and link_domain.

Custom Click Events

Use data-ga4-event for the event name and data-ga4-params for optional parameters (as a JSON string):

<button data-ga4-event="signup_click" data-ga4-params='{"source": "hero"}'>
    Sign Up
</button>

Automatic Parameter Extraction

When you use tracking on an <a> tag, the package automatically captures:

Parameter	Source	Description
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

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

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)

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

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