composer require alexwestergaard/php-ga4
L'Union européenne a notifié que Google Analytics n'est pas conforme au RGPD par défaut. En effet, le client frontal envoie les détails des visiteurs tels que leur adresse IP et les informations sur leur appareil avec des événements. Cela peut être évité grâce à un serveur intermédiaire dans la région européenne.
La configuration nécessite un ID de mesure et un secret API . Accédez à Administrateur (en bas à gauche) -> Compte -> Flux de données -> {Votre flux}. Ici, vous devriez trouver l'ID de mesure en haut et "Api Secrets for Measurement Protocol" un peu en bas de la page, où vous pouvez créer vous-même un API secret
.
Accédez à Administrator
(en bas à gauche), puis sélectionnez votre Account
-> Data Streams
-> votre flux.
Ici, vous trouverez Measurement-ID
en haut et plus bas Api Secrets for Measurement Protocol
, vous pouvez y créer vous-même un API Secret
.
Une fois que vous avez obtenu les informations d'identification, vous pouvez initialiser Analytics comme ceci :
use AlexWestergaard PhpGa4 Analytics ;
$ analytics = Analytics:: new (
measurement_id: ' G-XXXXXXXX ' ,
api_secret: ' xYzzX_xYzzXzxyZxX ' ,
debug: true | false #Default: False
);
Le marquage côté serveur n'est pas censé remplacer le client frontal et le lancement de la session doit se faire via le client gtag.js
Le flux par défaut est censé se produire comme suit :
_ga
et _gid
au client/GTAG.js_ga
(ou _gid
) pour envoyer/remplir les événements Remarque : Il est tout à fait possible de transmettre des événements au backend sans acquérir les cookies de session de Google Analytics ; Cependant, vous perdrez les informations regroupées dans la requête GTAG.js
si vous ne savez pas comment les transmettre également via le backend. Vous pouvez remplacer les sessions _ga
et _gid
par votre propre identifiant généré de manière unique.
Toutes les demandes doivent suivre cette structure et contenir au moins 1 événement pour que Google Analytics l'accepte.
Analytics [
Events [
Event {
Parameters
? Items [
Item Parameters
]
}
]
User Properties [
Properties {
Key: Value
}
]
? Consent {
Key: Value
}
? User Data {
Key: Value
}
]
Il s'agit d'une liste d'événements prédéfinis comme indiqué dans la documentation. Tous les événements ont les paramètres suivants pour localiser l'emplacement de déclenchement de chaque événement.
// Manual setting of each event
$ event -> setLanguage (string $ var );
$ event -> setPageLocation (string $ var );
$ event -> setPageReferrer (string $ var );
$ event -> setPageTitle (string $ var );
$ event -> setScreenResolution (string $ var );
// Fillable for multiple events
$ eventPage = AlexWestergaard PhpGa4 Helper EventParamsHelper ();
$ event -> setEventPage ( $ eventPage );
Cette bibliothèque est conçue pour le suivi côté serveur backend, mais vous déclencherez probablement la plupart des événements via le frontend avec Javascript ou Websockets. Il y aura 2 exemples, un comme backend pur pour les événements enregistrés/mis en file d'attente et un pour la communication frontend à backend.
use AlexWestergaard PhpGa4 Exception ;
use AlexWestergaard PhpGa4 Analytics ;
use AlexWestergaard PhpGa4 Event ;
use AlexWestergaard PhpGa4 Item ;
// require vendor/autoload.php
$ visitors = getVisitorsAndEvents (); // pseudo function, make your own logic here
foreach ( $ visitors as $ collection ) {
// Group of events, perhaps need logic to change from json or array to event objects
// Maybe its formatted well for the > ConvertHelper::parseEvents([...]) < helper
$ groups = $ collection [ ' events ' ];
// If gtag.js, this can be the _ga or _gid cookie
// This can be any kind of session identifier
// Usually derives from $_COOKIE['_ga'] or $_COOKIE['_gid'] set by GTAG.js
$ visitor = $ collection [ ' session_id ' ];
// load logged in user/visitor
// This can be any kind of unique identifier, readable is easier for you
// Just be wary not to use GDPR sensitive information
$ user = $ collection [ ' user_id ' ];
// Render events grouped on time (max offset is 3 days from NOW)
foreach ( $ groups as $ time => $ data ) {
try {
$ analytics = Analytics:: new ( $ measurementId , $ apiSecret )
-> setClientId ( $ visitor )
-> setTimestampMicros ( $ time );
if ( $ user !== null ) {
$ analytics -> setUserId ( $ user );
}
$ analytics -> addUserParameter (... $ data [ ' userParameters ' ]); // pseudo logic for adding user parameters
$ analytics -> addEvent (... $ data [ ' events ' ]); // pseudo logic for adding events
$ analytics -> post (); // send events to Google Analytics
} catch ( Exception Ga4Exception $ exception ) {
// Handle exception
// Exceptions might be stacked, check: $exception->getPrevious();
}
}
}
// array< array< eventName, array<eventParams> > >
axios . post ( "/your-api-endpoint/ga4-event-receiver" , [
// Note each event is its own object inside an array as
// this allows to pass the same event type multiple times
{
addToCart : {
currency : "EUR" ,
value : 13.37 ,
items : [
{
item_id : 1 ,
item_name : "Cup" ,
price : 13.37 ,
quantity : 1 ,
} ,
] ,
} ,
} ,
] ) ;
use AlexWestergaard PhpGa4 Helper ConvertHelper ;
use AlexWestergaard PhpGa4 Exception ;
use AlexWestergaard PhpGa4 Analytics ;
use AlexWestergaard PhpGa4 Event ;
// require vendor/autoload.php
try {
$ events = ConvertHelper:: parseEvents ( $ _POST );
Analytics:: new ( $ measurementId , $ apiSecret )
-> addEvent (... $ events )
-> post ();
} catch ( Exception Ga4Exception $ exception ) {
// Handle exception
// Exceptions might be stacked, check: $exception->getPrevious();
}
Vous pouvez créer vos propres événements personnalisés. Tout ce dont vous avez besoin est d’implémenter et de remplir la façade/interface AlexWestergaardPhpGa4FacadeTypeEventType
. Si vous souhaitez des fonctionnalités de simplicité de vie, vous pouvez étendre votre événement à partir de AlexWestergaardPhpGa4HelperEventHelper
et l'écraser comme bon vous semble.
// EventHelper implements AlexWestergaardPhpGa4FacadeTypeEventType
class ExampleEvent extends AlexWestergaard PhpGa4 Helper EventHelper
{
// variables should be nullable as unset() will set variable as null
protected null | mixed $ my_variable ;
protected null | mixed $ my_required_variable ;
// Arrays should always be instanciated empty
protected array $ my_array = [];
public function getName (): string
{
return ' example_event ' ;
}
public function getParams (): array
{
return [
' my_variable ' ,
' my_array ' ,
];
}
public function getRequiredParams (): array
{
return [
' my_required_variable ' ,
];
}
public function setMyVariable ( string $ value )
{
$ this -> my_variable = $ value ;
return $ this ; // Allows chained events
}
public function setMyRequiredVariable ( string $ value )
{
$ this -> my_required_variable = $ value ;
return $ this ; // Allows chained events
}
}
Le protocole de mesure pour GA4 possède une fonctionnalité de débogage qui peut être activée avec le paramètre debug
dans le constructeur Analytics.
$ analytics = Analytics:: new (
measurement_id: ' G-XXXXXXXX ' ,
api_secret: ' xYzzX_xYzzXzxyZxX ' ,
debug: true // default: false
);
Lorsque Debug
est activé, les événements sont envoyés à https://www.google-analytics.com/debug/mp/collect
où les problèmes seront détectés avec GA4Exception (Attention aux piles $exception->getPrevious()
) ; cette réponse ressemblera à ceci :
{
"validationMessages" : [
{
"fieldPath" : " events " ,
"description" : " Event at index: [0] has invalid name [_badEventName]. Names must start with an alphabetic character. " ,
"validationCode" : " NAME_INVALID "
}
]
}
Remarque : Cette bibliothèque valide déjà que les événements sont correctement formatés lorsqu'ils sont ajoutés aux analyses ( $analytics->addEvent(...)
).
Deux points importants :
debugView
dans l'administrateur Google Analytics. page_view
fonctionne, mais il n'est pas documenté dans la documentation officielle, alors ne vous y fiez pas.