Skip to content

joypixels/php-GA4-Measurement-Protocol

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Google Analytics 4 Measurement Protocol PHP Library

Coverage Status Latest Stable Version Total Downloads

Overview

This is a PHP Library facilitating the use of Google Analytics 4 (GA4) Measurement Protocol. Measurement Protocol allows developers to send events directly from server-side PHP to Google Analytics.

Please note that GA4 Measurement Protocol is in alpha and might encounter breaking changes. Full documentation is available here: https://developers.google.com/analytics/devguides/collection/protocol/ga4

Requirements

  • PHP >= 7.1
  • ext-json
  • guzzlehttp/guzzle: ^6.5.5

dev:

  • phpunit/phpunit: "^9.5"
  • fakerphp/faker: "^1.14"

Installation

The recommended way to install this library is via Composer (packagist package: br33f/php-ga4-mp).

Install by composer command:

composer require br33f/php-ga4-mp

or package.json

{
    "require": {
        "br33f/php-ga4-mp": "^0.1.0"
    }
}

Usage

Send View Item Event

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\ViewItemEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET', 'MEASUREMENT_ID');

// Create base request with required client_id
$baseRequest = new BaseRequest('CLIENT_ID');

// Create Event Data
$viewItemEventData = new ViewItemEvent();
$viewItemEventData
    ->setValue(51.10)
    ->setCurrency('EUR');

// Create Item
$viewedItem = new ItemParameter();
$viewedItem
    ->setItemId('ITEM_ID')
    ->setItemName('ITEM_NAME')
    ->setPrice(25.55)
    ->setQuantity(2);
    
// Add this item to viewItemEventData   
$viewItemEventData->addItem($viewedItem)

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($viewItemEventData);

// We have all the data we need. Just send the request.
$ga4Service->send($baseRequest);

Send Purchase Event

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\PurchaseEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET', 'MEASUREMENT_ID');

// Create base request with required client_id
$baseRequest = new BaseRequest('CLIENT_ID');

// Create Event Data
$purchaseEventData = new PurchaseEvent();
$purchaseEventData
    ->setValue(250.00)
    ->setCurrency('USD');

// Create Item
$purchasedItem1 = new ItemParameter();
$purchasedItem1
    ->setItemId('FIRST_ITEM_ID')
    ->setItemName('FIRST_ITEM_NAME')
    ->setPrice(100.00)
    ->setQuantity(2);
    
// Add this item to purchaseEventData
$purchaseEventData->addItem($purchasedItem1)

// You can also fill item data via constructor
$purchaseEventData->addItem(new ItemParameter([
    'item_id' => 'SECOND_ITEM_ID',
    'item_name' => 'SECOND_ITEM_NAME',
    'price' => 50.00,
    'quantity' => 1
]));

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($purchaseEventData);

// We have all the data we need. Just send the request.
$ga4Service->send($baseRequest);

At the moment, the library contains the defined structures of the following events:

Event name Structure Documentation
add_payment_info AddPaymentInfoEvent see documentation
add_shipping_info AddShippingInfoEvent see documentation
add_to_cart AddToCartEvent see documentation
begin_checkout BeginCheckoutEvent see documentation
login LoginEvent see documentation
purchase PurchaseEvent see documentation
refund RefundEvent see documentation
remove_from_cart RemoveFromCartEvent see documentation
search SearchEvent see documentation
select_item SelectItemEvent see documentation
sign_up SignUpEvent see documentation
view_cart ViewCartEvent see documentation
view_item ViewItemEvent see documentation
view_search_results ViewSearchResultsEvent see documentation

These events are sent analogously to the examples presented above.

Other events

In order to send any event one can use BaseEvent structure and add any data. Please note that specific event structure should be used instead if already defined, since BaseEvent does not force any structure or provide data validation.

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\BaseEvent;

// Create Service and request same as above
// ...

// Create Base Event Data (for example: 'share' event - https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#share)
$eventName = 'share'; 
$anyEventData = new BaseEvent($eventName);
$purchaseEventData
    ->setMethod('Twitter')
    ->setContentType('Post')
    ->setItemId('example_item_id')
    ->setAnyParamYouWish('test'); // means 'any_param_you_wish' is set


// Add event to base request (you can add up to 25 events to single request) and send, same as above
// ...

Debug event data and requests

Debuging event data is possible by sending them to debug endpoint (Measurement Protocol Validation Server), since default endpoint for Google Analytics 4 Measurement Protocol does not return any HTTP error codes or messages. In order to validate event one should use sendDebug($request) method instead of send($request).

Method sendDebug($request) returns DebugResponse object, which is hydrated with response data such as: status_code and validation_messages.

Example:

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\AddToCartEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET', 'MEASUREMENT_ID");

// Create base request with required client_id
$baseRequest = new BaseRequest('CLIENT_ID');

// Create Invalid Event Data
$addToCartEventData = new AddToCartEvent();
$addToCartEventData
    ->setValue(99.99)
    ->setCurrency('SOME_INVALID_CURRENCY_CODE'); // invalid currency code

// addItem
$addToCartEventData->addItem(new ItemParameter([
    'item_id' => 'ITEM_ID',
    'item_name' => 'ITEM_NAME',
    'price' => 99.99,
    'quantity' => 1
]));

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($addToCartEventData);

// Instead of sending data to production Measurement Protocol endpoint
// $ga4Service->send($baseRequest); 
// Send data to validation endpoint, which responds with status cude and validation messages.
$debugResponse = $ga4Service->sendDebug($baseRequest);

// Now debug response contains status code, and validation messages if request is invalid
var_dump($debugResponse->getStatusCode()); 
var_dump($debugResponse->getValidationMessages());

Unit Testing

Unit Testing for this module is done using PHPUnit 9.

Running unit tests:

composer install
php vendor/bin/phpunit

License

This library is released under the MIT License.

About

PHP GoogleAnalytics4 Measurement Protocol Library

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%