Download the PHP package alexwestergaard/php-ga4 without Composer

Europe - GDPR Notice

The European Union have notified that Google Analytics does not comply with GDPR by default. This is because the frontend Client sends visitor details like their IP Address and device information with events. This can be avoided with a middle-man server inside the European Region.

• Source: Europe, GDPR, Schrems II
• Options: Privacy controls in Google Analytics

Getting started

Setup requires a Measurement ID and API Secret. Go to Administrator (Bottom left) -> Account -> Data Streams -> {Your Stream}. Here you should find Measurement ID at top and "Api Secrets for Measurement Protocol" a little down the page, where you can create yourself an API secret.

Go to Administrator (bottom left) and then select your Account -> Data Streams -> your stream.
Here you will find Measurement-ID at top from and further down Api Secrets for Measurement Protocol, in there you can create yourself an API Secret.

Once you have obtained the credentials, you can initialise the Analytics like this:

Data flow

Server Side Tagging is not supposed to replace the frontend Client and session initiation should happen through the gtag.js Client. The default flow is supposed to happen as follows:

1. Obtain proper GDPR Consent
2. Client/GTAG.js initiates session with Google Analytics
3. Google Analytics sends _ga and _gid cookies back to Client/GTAG.js
4. Server uses _ga (or _gid) to send/populate events
   • Eg. GenerateLead, Purchase, Refund and other backend handled events.

Note: It is entirely possible to push events to backend without acquiring the session cookies from Google Analytics; you will, however, lose information bundled inside the GTAG.js request if you do not figure out how to push that via backend too. You can replace the _ga and _gid sessions with your own uniquely generated id.

All requests should follow this structure and contain at least 1 event for Google Analytics to accept it.

Events

This is a list of prebuilt events as shown in the documentation. All events have the following parameters to locate trigger location of each event.

Default

E-commerce

Engagement / Gaming

Frontend & Backend Communication

This library is built for backend server side tracking, but you will probably trigger most events through frontend with Javascript or Websockets. There will be 2 examples, one as pure backend for logged/queued events and one for frontend to backend communication.

Logging / Queue

Frontend => Backend

Frontend

Backend

Custom Events

You can build your own custom events. All you need is to implement and fullfill the AlexWestergaard\PhpGa4\Facade\Type\EventType facade/interface. If you want ease of life features, then you can extend your event from AlexWestergaard\PhpGa4\Helper\EventHelper and overwrite as you see fit.

Debug

Measurement protocol for GA4 has debug functionality that can be enabled with the debug parameter in the Analytics constructor.

When Debug is enabled then events are sent to https://www.google-analytics.com/debug/mp/collect where issues will be caught with GA4Exception (Be aware of $exception->getPrevious() stacks); such response will look as follows:

Notice: This library already validates that events are properly formatted when added to analytics ($analytics->addEvent(...)).

Two important points:

• Events sent to the Validation Server will not show up in reports.
• There is no way for events sent through measurement protocol (Server Side) to show up in the debugView in Google Analytics Admin.

Additional information

• Geographic information is only available via automatic collection from gtag, Google Tag Manager, or Google Analytics for Firebase.
• The page_view event works, however it's not documented in the official documentation, so do not rely on it.

Documentation

• Measurement Protocol
• Measurement Protocol: Reference
• Measurement Protocol: User Properties
• Measurement Protocol: Events
  • Reserved Event Names
• Measurement Protocol: Validation
• Measurement Protocol: User Data