Download the PHP package schenke-io/laravel-ga4-marketing without Composer

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.
• 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
  • Features
  • Installation
  • Client-Side Setup
  • Configuration
    • Advanced Configuration
  • Usage
  • 1. Standard Mode (Quick Setup)
  • 2. Advanced Mode (Vite & Bundling)
  • 3. Server-Side Only Mode
  • 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
  • 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:

You should publish the config file with:

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:

Configuration

Set up your Google Analytics 4 credentials in your .env file:

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:

Usage

This package supports three primary integration modes to suit different application architectures.

1. Standard Mode (Quick Setup)

Best for most applications. Simply add the @Ga4MarketingScript directive to your main layout file, typically before the closing </body> tag:

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)

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:

Blade Setup: Add the @Ga4MarketingConfig directive in your layout. This provides the necessary configuration (route, CSRF token) to the bundled script:

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

For tracking without any client-side scripts, you can rely entirely on the track-page-view middleware and the AnalyticsService.

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 <body> tag.

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

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:

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.

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.

Sending Custom Events

You can also use the AnalyticsService to send custom events manually:

Recommended Events

The AnalyticsService provides helper methods for standard GA4 events using camelCase naming:

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:

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.

JavaScript Event Bridging

To send events from JavaScript, you can use the window.ga4Event helper:

Visibility 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

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" (or data-ga4="outbound") on an <a> tag:

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 (or data-ga4) for the event name and data-ga4-params for optional parameters (as a JSON string):

Automatic Parameter Extraction

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

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:

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:

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:

Markdown file generated by schenke-io/packaging-tools