Download the PHP package internetrix/silverstripe-ga-measurement-protocol without Composer
On this page you can find all versions of the php package internetrix/silverstripe-ga-measurement-protocol. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download internetrix/silverstripe-ga-measurement-protocol
More information about internetrix/silverstripe-ga-measurement-protocol
Files in internetrix/silverstripe-ga-measurement-protocol
Package silverstripe-ga-measurement-protocol
Short Description Send Google Analytics data server-side
License BSD-3-Clause
Informations about the package silverstripe-ga-measurement-protocol
Google Analytics Measurement Protocol v1 for SilverStripe
Introduction
This module adds functionality to be able to send hits to Google Analytics via server side using Google's Measurement Protocol Version 1: https://developers.google.com/analytics/devguides/collection/protocol/v1
The module currently allows the sending of the following hits:
- pageviews
- events
- timing
This is accomplished by constructing a GET request and using Guzzle to send the request to the Google Analytics endpoint.
Requirements
- SilverStripe CMS ^4.0
- Guzzle ^6.3
Installation
Install the module via composer:
Configuration & Setup
- Set the following variables for
Internetrix\GaMeasurementProtocol\Model\GAHit
in config:- useProductionGAProperty: Set this true if you want to use the Production tracking ID. Set to false if you want to send hits to staging.
- stagingTrackingID: Google Analytics UA tracking ID for staging/testing property. Expected format: 'UA-XXXXXXXX-X'
- productionTrackingID: Google Analytics UA tracking ID for production property. Expected format: 'UA-XXXXXXXX-X'
Example YML configuration:
Optional: Another useful config variable that is useful for debugging / testing is to set to true in config:
By setting useTestingEndpoint to true, when sending hits, the module will send the request to Google's Validation Server.
As Google's GA Measurement Protocol does not return HTTP error codes, by sending requests to the Measurement Protocol Validation Server, you can test the response. If the current SS environment is set to dev, it will also output the response to the browser / terminal.
More information on Google's Measurement Protocol Validation Server can be found here: https://developers.google.com/analytics/devguides/collection/protocol/v1/validating-hits
Sending hits to a Production Google Analytics property
For hits to be sent to a Production property, all the following conditions must be met. Otherwise hits will ALWAYS be sent to staging property / debug endpoint.
- Condition 1 - SilverStripe
SS_ENVIRONMENT_TYPE
variable must be set tolive
- Condition 2 -
useProductionGAProperty
must be set to true in config - Condition 3 -
useTestingEndpoint
must be set to false in config
Generate ClientID
IMPORTANT: When sending a GA hit, always ensure that the hit type is set and that a unique client ID is given. This module contains a function called setClientID to help developers add a client ID. The first parameter of function tells the function if the _ga cookie should be retrieved or not when creating a clientID. The second parameters allows a developer to override the clientID for a hit.
There are some ways this function can be used:
-
Option 1: Retrieve the same ClientID using the _ga cookie (shared by frontend)
$pageHit->setClientID(true);
-
Option 2: Generate a completely new unique client ID. If this option is saved, the unique client ID should be saved by the developer and re-used so that Google Analytics recognises the same user
$pageHit->setClientID(false);
- Option 3: Override and set the GA Client ID to a value arbitrarily defined by a developer
$pageHit->setClientID(false, '<CUSTOM-CLIENT-ID>);
Usage Examples
The PHPDocs in GAHit.php contains links explaining what parameters are required for each type of event. Otherwise, please refer to the Official Google Analytics Measurement Protocol documentation
Example 1: Sending a Pageview hit to GA
Required Parameters:
- HitType = pageview
- Set a GA Client ID by calling:
$hit->setClientID
. See above Generate ClientID section for more details - Include either (Document Hostname + Document Path + (optionally) Document Title) OR set the Document Location URL
- Set a User-Agent by calling:
$hit->setUserAgent()
otherwise Google Analytics may classify the hit as bot spam
Example 2: Sending an Event hit to GA
Required Parameters:
- HitType = event
- Set a GA Client ID by calling:
$hit->setClientID
. See above Generate ClientID section for more details - Set a User-Agent by calling:
$hit->setUserAgent()
otherwise Google Analytics may classify the hit as bot spam - Event Category and Event Action are required parameters. Event Label and Event Value is optional. Set these parameters by calling:
$hit->setEventParameters('category', 'action', 'label', $value)
Example 3: Sending a Timing hit to GA
Required Parameters:
- HitType = timing
- Set a GA Client ID by calling:
$hit->setClientID
. See above Generate ClientID section for more details - Set a User-Agent by calling:
$hit->setUserAgent()
otherwise Google Analytics may classify the hit as bot spam - Timing category, timing variable and timing timing are required. Set these parameters by calling:
$hit->setTimingParameters($category, $userTimingVariable, $timingTime, $optionalParameters)
Adding Custom Dimensions, Custom Metrics and / or adding extra parameters to a hit
To add additional parameters like Custom Dimensions, Custom Metrics etc to a hit, use the addParameters
method where $parameters
should be an array with parameter name
as the key, and the parameter value
as the array value:
Todo
- Add support for other type of hits such as transactions etc.
Licence
Please see License File for more information.
All versions of silverstripe-ga-measurement-protocol with dependencies
silverstripe/framework Version ^4.0.0
silverstripe/cms Version ^4.0.0
guzzlehttp/guzzle Version ^6.3