Skip to content

Commit 757b877

Browse files
author
Alex Westergaard
committed
Improve README
1 parent c7f3487 commit 757b877

File tree

1 file changed

+76
-91
lines changed

1 file changed

+76
-91
lines changed

‎README.md‎

Lines changed: 76 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,23 @@ PHP Wrapper for Google Analytics 4 with Server Side Tracking
44
[![Release Size](https://img.shields.io/github/languages/code-size/alexwestergaard/php-ga4?color=blue&style=for-the-badge)](https://github.com/AlexWestergaard/php-ga4/releases/latest)
55
[![Issues](https://img.shields.io/github/issues-raw/alexwestergaard/php-ga4?color=red&style=for-the-badge)](https://github.com/AlexWestergaard/php-ga4/issues)
66

7-
`composer require alexwestergaard/php-ga4`
8-
9-
- [GDPR Notice](#gdpr-notice)
10-
- [Events](#events)
11-
- [Default](#default)
12-
- [E-commerce](#e-commerce)
13-
- [Engagement / Gaming](#engagement--gaming)
14-
- [Frontend \& Backend Communication](#frontend--backend-communication)
15-
- [Logged/Queued Events](#loggedqueued-events)
16-
- [Frontend to Backend communication](#frontend-to-backend-communication)
17-
- [Custom Events](#custom-events)
18-
- [Documentation](#documentation)
19-
20-
**LEGACY WARNING**
7+
```sh
8+
composer require alexwestergaard/php-ga4
9+
```
10+
11+
- [LEGACY](#legacy)
12+
13+
14+
## LEGACY
2115
- `PHP 7` should only use `1.0.*` versions of this library
2216

2317
## GDPR Notice
2418

25-
*European Union have noticed that default setup of Google Analytics does not comply with GDPR as data is sent unrestricted to an american service possibly outside of Europe. This includes the use of 'GTAG.js' as JavaScript pushes the request from visitors device including IP-Address. Server Side Tracking, however, does only send information specified inside the body and of your server. Relying solely on Google Analytics 4 Events - that is not pushed through the GTAG.js script - can be scraped of GDPR-related information.*
19+
> European Union have noticed that default setup of Google Analytics does not comply with GDPR as data is sent unrestricted to an american service possibly outside of Europe.
20+
>
21+
> This includes the use of `gtag.js`/`gtm.js` as JavaScript pushes the request from visitors device including their IP-Address. Server Side Tracking, however, does only send information specified inside the body and about your server.
22+
>
23+
> Relying solely on Google Analytics 4 Events - that is not pushed through the `gtag.js`/`gtm.js` script - can be scraped of GDPR-related information.
2624
2725
- Source: Europe, GDPR, Schrems II
2826
- https://support.google.com/analytics/answer/9019185?hl=en
@@ -72,120 +70,107 @@ This is a list of prebuilt events as shown in the documentation.
7270
## Frontend & Backend Communication
7371

7472
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.
75-
76-
### Logged/Queued Events
73+
74+
### Logging / Queues
7775

7876
```php
77+
7978
use AlexWestergaard\PhpGa4\Exception;
8079
use AlexWestergaard\PhpGa4\Analytics;
8180
use AlexWestergaard\PhpGa4\Event;
8281
use AlexWestergaard\PhpGa4\Item;
8382

84-
require_once __DIR__ . '/vendor/autoload.php';
83+
// require vendor/autoload.php
8584

86-
try {
87-
$analytics = Analytics::new('G-XXXXX', 'secret_api_key')
88-
->setClientId('session_id');
89-
// ^ If gtag.js, this can be the _ga or _gid cookie
90-
91-
if ($user) {
92-
$analytics->setUserId($user->id);
93-
// ^ This can be any kind of identifier, readable is easier for you
94-
}
85+
// If gtag.js, this can be the _ga or _gid cookie
86+
// This can be any kind of session identifier
87+
$session = $_COOKIE['_ga'] ?? $_COOKIE['_gid'] ?? $_COOKIE['PHPSESSID'];
9588

96-
$addToCart = Event\AddToCart::new()
97-
->setCurrency($cart->currency)
98-
->setValue($cart->total);
99-
100-
foreach($cart->products as $product) {
101-
$addToCart->addItem(
102-
Item::new()
103-
->setItemId($product['id'])
104-
->setItemName($product['name'])
105-
->setQuantity($product['quantity'])
106-
->setPrice($product['price_total'])
107-
->setItemVariant($product['colorName'])
108-
);
109-
}
89+
// Render events grouped on time
90+
foreach ($groups as $time => $data) {
91+
try {
92+
$analytics = Analytics::new($measurementId, $apiSecret)
93+
->setClientId($session)
94+
->setTimestampMicros($time);
11095

111-
$analytics->addEvent($addToCart);
96+
// load logged in user/visitor
97+
if ($auth) {
98+
// This can be any kind of identifier, readable is easier for you
99+
// Just be wary not to use GDPR sensitive information
100+
$analytics->setUserId($auth->id);
101+
}
112102

113-
// Errors are served as exceptions on pre-exit
114-
$analytics->post();
115-
} catch (Exception\Ga4Exception $exception) {
116-
// Handle exception
117-
// Exceptions might be stacked, check: $exception->getPrevious();
118-
}
103+
$analytics->addUserParameter(...$data['userParameters']);
104+
$analytics->addEvent(...$data['events']);
119105

120-
//// ==============================================================
121-
// You can instanciate events with 'fromArray' method as of v1.0.9
122-
// This allows for quick-events by recursive instanciation
123-
$analytics->addEvent(
124-
Event\AddToCart::fromEvent([
125-
'currency' => $cart->currency,
126-
'value' => $cart->total,
127-
// Items must be array of Items models
128-
'items' => array_map(
129-
function ($product) {
130-
return Item::fromArray([
131-
'item_id' => $product->id,
132-
'item_name' => $product->name,
133-
'quantity' => $product->quantity,
134-
'price' => $product->price,
135-
]);
136-
},
137-
$cart->products
138-
),
139-
])
140-
);
141-
//// ==============================================================
106+
$analytics->post();
107+
} catch (Exception\Ga4Exception $exception) {
108+
// Handle exception
109+
// Exceptions might be stacked, check: $exception->getPrevious();
110+
}
111+
}
142112
```
143113

144-
### Frontend to Backend communication
114+
### Frontend => Backend
115+
116+
#### Frontend
145117

146118
```js
147-
axios.post('/api/ga4', {
148-
addToCart: {
149-
currency: 'EUR',
150-
value: 13.37,
151-
items: [
152-
{
153-
'item_id': 1,
154-
'item_name': 'Cup',
155-
'price': 13.37,
156-
'quantity': 1
157-
}
158-
]
119+
axios.post('/api/ga4', [
120+
{
121+
addToCart: {
122+
currency: 'EUR',
123+
value: 13.37,
124+
items: [
125+
{
126+
'item_id': 1,
127+
'item_name': 'Cup',
128+
'price': 13.37,
129+
'quantity': 1
130+
}
131+
]
132+
}
159133
}
160-
})
134+
])
161135
```
162136

137+
#### Backend
138+
163139
```php
140+
use AlexWestergaard\PhpGa4\Helper\Converter;
141+
use AlexWestergaard\PhpGa4\Exception;
164142
use AlexWestergaard\PhpGa4\Analytics;
165143
use AlexWestergaard\PhpGa4\Event;
166144

145+
// require vendor/autoload.php
146+
167147
try {
168-
$addToCart = Event\AddToCart::fromArray($_POST['addToCart']);
148+
$events = Converter::parseEvents($_POST);
149+
169150
Analytics::new($measurementId, $apiSecret)
170-
->addEvent($addToCart)
151+
->addEvent(...$events)
171152
->post();
172-
} catch (GA4Exception $exception) {
153+
} catch (Exception\Ga4Exception $exception) {
173154
// Handle exception
174155
// Exceptions might be stacked, check: $exception->getPrevious();
175156
}
176157
```
177158

178159
## Custom Events
179160

180-
You can build your own custom events, but be careful to follow this structure. It is important that you implement the `AlexWestergaard\PhpGa4\Facade\Type\TypeEvent` class because Analytics checks inheritance towards that class on addEvent.
161+
You can build your own custom events. All you need is to implement and fullfill the `AlexWestergaard\PhpGa4\Facade\Type\Event` facade/interface. If you want ease of life features, then you can extend your event from `AlexWestergaard\PhpGa4\Helper\AbstractEvent` and overwrite as you see fit.
181162

182163
```php
183164

184-
class ExampleEvent extends AlexWestergaard\PhpGa4\Helper\AbstractEvent // AbstractEvent implements AlexWestergaard\PhpGa4\Facade\Type\TypeEvent
165+
// AbstractEvent implements AlexWestergaard\PhpGa4\Facade\Type\TypeEvent
166+
class ExampleEvent extends AlexWestergaard\PhpGa4\Helper\AbstractEvent
185167
{
186-
protected null|mixed $my_variable; // variables should be nullable as unset() will set variable as null
187-
protected array $my_array = []; // Arrays should always be instanciated empty
168+
// variables should be nullable as unset() will set variable as null
169+
protected null|mixed $my_variable;
188170
protected null|mixed $my_required_variable;
171+
172+
// Arrays should always be instanciated empty
173+
protected array $my_array = [];
189174

190175
public function getName(): string
191176
{

0 commit comments

Comments
 (0)