Add support for session_id and timestamp_micros

See https://www.analyticsmania.com/post/unassigned-in-google-analytics-4/#measurement-protocol

> If your developers send data via MP to the currently active session on your site, each event must contain client_id and session_id parameters. If session_id is not included (or the session_id does not match the ID of the currently active session), the traffic source of that session will be not set.

> If your developers send data via MP to the session that has already timed out (but is not older than 72 hours), they also need to send a timestamp_micros parameter. If that is not done, then you guessed it – the source/medium will be not set.

Author: LukeTowers

README.md

@@ -84,11 +84,44 @@ class OrderWasCreated implements ShouldBroadcastToAnalytics
 }
 ```
 
-There are two additional methods that lets you customize the call sent to GA4.
+There are additional methods that let you customize the call sent to GA4.
 
-With the `broadcastGA4EventAs` method you can customize the name of the [Event Action](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventAction). By default, we use the class name with the class's namespace removed. This method gives you access to the underlying `GA4` class instance as well.
+#### `broadcastGA4EventAs`
 
-With the `withGA4Parameters` method you can set the parameters of the event being sent.
+With this method you can customize the name of the [Event Action](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventAction). By default, we use the class name with the class's namespace removed. This method gives you access to the underlying `GA4` class instance as well.
+
+#### `eventOccurredAt`
+
+With this method you can customize the time that the event occurred at. This will be used in the `timestamp_micros` parameter sent to the Measurement Protocol. By default, we use the current time. You must return an instance of `Carbon\Carbon` in order for it to be used.
+
+```php
+use Carbon\Carbon;
+use DevPro\GA4EventTracking\GA4;
+use DevPro\GA4EventTracking\ShouldBroadcastToAnalytics;
+use Illuminate\Queue\SerializesModels;
+
+class OrderSubmitted extends Event implements ShouldBroadcastToAnalytics
+{
+    use SerializesModels;
+
+    protected Carbon $submittedAt;
+
+    public function __construct(
+        public Order $order
+    ) {
+        $this->submittedAt = now();
+    }
+
+    public function eventOccurredAt(): Carbon
+    {
+        return $this->submittedAt;
+    }
+}
+```
+
+#### `withGA4Parameters`
+
+With this method you can set the parameters of the event being sent.
 
 ```php
 <?php

config/config.php

@@ -22,10 +22,15 @@
     'api_secret' => env('GA4_MEASUREMENT_PROTOCOL_API_SECRET', null),
 
     /**
-     * The session key to store the Client ID in.
+     * The session key to store the GA4 Client ID in.
      */
     'client_id_session_key' => 'ga4-event-tracking-client-id',
 
+    /**
+     * The session key to store the GA4 Session ID in.
+     */
+    'session_id_session_key' => 'ga4-event-tracking-session-id',
+
     /**
      * HTTP URI to post the Client ID to (from the Blade Directive).
      */

resources/views/sendClientID.blade.php

@@ -1,27 +1,44 @@
 <script>
-    function postClientId(clientId) {
+    function ga4PostId(id, value) {
         let data = new FormData();
-        data.append('client_id', clientId);
+        data.append(id, value);
         let xhr = new XMLHttpRequest();
         xhr.open('POST', "{{ url(config('ga4-event-tracking.http_uri'))}}", true);
         xhr.setRequestHeader('X-CSRF-TOKEN', '{{ csrf_token() }}');
         xhr.send(data);
     }
 
+    function postClientId(clientId) {
+        ga4PostId('client_id', clientId);
+    }
+
+    function postSessionId(sessionId) {
+        ga4PostId('session_id', sessionId);
+    }
+
     function collectClientId() {
         if (typeof ga !== 'undefined') {
             ga(function () {
                 let clientId = ga.getAll()[0].get('clientId');
                 if (clientId !== @json(app('ga4-event-tracking.client-id'))) {
                     postClientId(clientId);
                 }
+                let sessionId = ga.getAll()[0].get('sessionId');
+                if (sessionId !== @json(app('ga4-event-tracking.session-id'))) {
+                    postSessionId(sessionId);
+                }
             });
         } else if (typeof gtag !== 'undefined') {
             gtag('get', @json(config('ga4-event-tracking.measurement_id')), 'client_id', function (clientId) {
                 if (clientId !== @json(app('ga4-event-tracking.client-id'))) {
                     postClientId(clientId);
                 }
             });
+            gtag('get', @json(config('ga4-event-tracking.measurement_id')), 'session_id', function (sessionId) {
+                if (sessionId !== @json(app('ga4-event-tracking.session-id'))) {
+                    postSessionId(sessionId);
+                }
+            });
         }
     }
 

src/Events/BroadcastEvent.php

@@ -2,6 +2,7 @@
 
 namespace DevPro\GA4EventTracking\Events;
 
+use Carbon\Carbon;
 use DevPro\GA4EventTracking\GA4;
 
 class BroadcastEvent implements EventBroadcaster
@@ -32,6 +33,14 @@ public function handle($event): void
             $this->GA4->setEventParams($event->withGA4Parameters($this->GA4));
         }
 
+        $occurredAt = Carbon::now();
+        if (method_exists($event, 'eventOccurredAt')) {
+            $occurredAt = $event->eventOccurredAt();
+        }
+        if ($occurredAt instanceof Carbon) {
+            $this->GA4->setTimestampMicros($occurredAt->timestamp . $occurredAt->micro);
+        }
+
         $this->GA4->sendAsSystemEvent();
     }
 }

src/GA4.php

@@ -14,6 +14,10 @@ class GA4
 
     protected string $userId = '';
 
+    protected string $timestampMicros = '';
+
+    protected ?string $sessionId = null;
+
     protected array $userProperties = [];
 
     protected bool $debugging = false;
@@ -113,6 +117,24 @@ public function setUserId(string $userId): static
         return $this;
     }
 
+    public function setTimestampMicros(string $timestampMicros): static
+    {
+        // @TODO: Perform validation on this to ensure it's a valid timestamp
+        $this->timestampMicros = $timestampMicros;
+        return $this;
+    }
+
+    public function setSessionId(string $sessionId): static
+    {
+        $this->sessionId = $sessionId;
+        return $this;
+    }
+
+    public function getSessionId(): ?string
+    {
+        return $this->sessionId;
+    }
+
     public function setUserProperties(array $userProperties): static
     {
         $this->userProperties = $userProperties;
@@ -131,6 +153,12 @@ public function setEventAction(string $eventAction): void
 
     public function setEventParams(array $eventParams): void
     {
+        if (!isset($eventParams['session_id']) && !is_null($this->sessionId)) {
+            // Required to have events show up in session based reporting
+            // @see https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag#format_the_request
+            $eventParams['session_id'] = $this->sessionId;
+        }
+
         $this->eventParams = $eventParams;
     }
 
@@ -186,6 +214,12 @@ public function sendEvents(array $events): array
             $requestData['user_id'] = $this->userId;
         }
 
+        if (!empty($this->timestampMicros)) {
+            // @TODO: Perform validation on this to ensure that it's within the past 72 hours
+            // @see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#payload_post_body
+            $requestData['timestamp_micros'] = $this->timestampMicros;
+        }
+
         if (!empty($this->userProperties)) {
             $requestData['user_properties'] = $this->userProperties;
         }

src/Http/SessionIdRepository.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace DevPro\GA4EventTracking\Http;
+
+interface SessionIdRepository
+{
+    public function update(string $sessionId): void;
+
+    public function get(): ?string;
+}

src/Http/SessionIdSession.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace DevPro\GA4EventTracking\Http;
+
+use Illuminate\Session\Store;
+
+class SessionIdSession implements SessionIdRepository
+{
+    private Store $session;
+
+    private string $key;
+
+    public function __construct(Store $session, string $key)
+    {
+        $this->session = $session;
+        $this->key = $key;
+    }
+
+    /**
+     * Stores the GA4 Session ID in the session.
+     */
+    public function update(string $sessionId): void
+    {
+        $this->session->put($this->key, $sessionId);
+    }
+
+    /**
+     * Gets the GA4 Session ID from the session or generates one.
+     */
+    public function get(): ?string
+    {
+        return $this->session->get($this->key, fn () => $this->generateId());
+    }
+
+    /**
+     * Generates a GA4 Session ID and stores it in the session.
+     */
+    private function generateId(): string
+    {
+        return tap(now()->timestamp, fn ($id) => $this->update($id));
+    }
+}

src/Http/StoreClientIdInSession.php

@@ -8,13 +8,19 @@
 class StoreClientIdInSession
 {
     /**
-     * Stores the posted Client ID in the session.
+     * Stores the posted GA4 Client ID or Session ID in the session.
      */
-    public function __invoke(Request $request, ClientIdSession $clientIdSession): JsonResponse
+    public function __invoke(Request $request, ClientIdSession $clientIdSession, SessionIdSession $sessionIdSession): JsonResponse
     {
-        $data = $request->validate(['client_id' => 'required|string|max:255']);
+        if ($request->has('client_id')) {
+            $data = $request->validate(['client_id' => 'required|string|max:255']);
+            $clientIdSession->update($data['client_id']);
+        }
 
-        $clientIdSession->update($data['client_id']);
+        if ($request->has('session_id')) {
+            $data = $request->validate(['session_id' => 'required|string|max:255']);
+            $sessionIdSession->update($data['session_id']);
+        }
 
         return response()->json();
     }

src/ServiceProvider.php

@@ -6,6 +6,8 @@
 use DevPro\GA4EventTracking\Events\EventBroadcaster;
 use DevPro\GA4EventTracking\Http\ClientIdRepository;
 use DevPro\GA4EventTracking\Http\ClientIdSession;
+use DevPro\GA4EventTracking\Http\SessionIdRepository;
+use DevPro\GA4EventTracking\Http\SessionIdSession;
 use DevPro\GA4EventTracking\Http\StoreClientIdInSession;
 use DevPro\GA4EventTracking\Listeners\DispatchAnalyticsJob;
 use Illuminate\Support\Facades\Blade;
@@ -89,15 +91,25 @@ protected function registerAnalytics()
     protected function registerClientId()
     {
         $this->app->singleton(ClientIdRepository::class, ClientIdSession::class);
+        $this->app->singleton(SessionIdRepository::class, SessionIdSession::class);
 
         $this->app->bind('ga4-event-tracking.client-id', function () {
             return $this->app->make(ClientIdSession::class)->get();
         });
+        $this->app->bind('ga4-event-tracking.session-id', function () {
+            return $this->app->make(SessionIdSession::class)->get();
+        });
 
         $this->app->singleton(ClientIdSession::class, function () {
             return new ClientIdSession(
                 $this->app->make('session.store'),
-                config('ga4-event-tracking.client_id_session_key')
+                config('ga4-event-tracking.client_id_session_key', 'ga4-event-tracking-client-id')
+            );
+        });
+        $this->app->singleton(SessionIdSession::class, function () {
+            return new SessionIdSession(
+                $this->app->make('session.store'),
+                config('ga4-event-tracking.session_id_session_key', 'ga4-event-tracking-session-id')
             );
         });
     }