README

Use this bundle to track your visitors with Google Analytics, but using server side integration instead of the usual client side integration.

This bundle is based on the Google Analytics measurement protocol library which in turn is based on the Universal Analytics solution from Google. The new GA4 tracking solution will be implemented when it's feature complete and out of beta.

Installation

This bundle also depends on the Client Id Bundle and the Consent Bundle, which generates client ids and provides consent services respectively. If you're not bound by the EU cookie laws, take a look at the configuration of the Consent Bundle to have consent granted by default.

To install this bundle, simply run:

composer require setono/google-analytics-server-side-tracking-bundle

This will install the bundle and enable it if you're using Symfony Flex. If you're not using Flex, add the bundle manually to bundles.php instead.

Create migration

Hits are saved in the database, so you need to create a migration file:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Configuration

To enable the tracking, you need to supply Google Analytics properties to track:

# config/packages/setono_google_analytics_server_side_tracking.yaml
setono_google_analytics_server_side_tracking:
    properties:
        - "UA-123456-78"
        - "UA-345656-81" # Notice you can add as many properties as you'd like

If you have your properties stored somewhere else, i.e. in a database, you can just implement the Setono\GoogleAnalyticsServerSideTrackingBundle\Provider\PropertyProviderInterface which returns a list of properties.

You can also configure the minimum amount of seconds before hits are sent to Google:

# config/packages/setono_google_analytics_server_side_tracking.yaml
setono_google_analytics_server_side_tracking:
    send_delay: 600 # Wait a minimum of 10 minutes before sending a hit

Usage

Out of the box, the bundle will start tracking visitors just like the client side integration will, but just as with the client side integration you may want to add custom tracking specific to your application. Here's an example of the ecommerce event Purchase:

<?php

use Setono\GoogleAnalyticsMeasurementProtocol\DTO\Event\PurchaseEventData;
use Setono\GoogleAnalyticsMeasurementProtocol\DTO\ProductData;
use Setono\GoogleAnalyticsServerSideTrackingBundle\Factory\HitBuilderFactoryInterface;

final class YourService
{
    private HitBuilderFactoryInterface $hitBuilderFactory;

    public function __construct(HitBuilderFactoryInterface $hitBuilderFactory)
    {
        $this->hitBuilderFactory = $hitBuilderFactory;
    }

    public function track(): void
    {
        $hitBuilder = $this->hitBuilderFactory->createEventHitBuilder();

        $purchaseEvent = new PurchaseEventData('ORDER123', 'example.com', 431.25, 'EUR', 8.43, 2.56);

        $product1 = ProductData::createAsProductType('BLACK_T_SHIRT_981', 'Black T-shirt');
        $product1->brand = 'Gucci';
        $product1->quantity = 2;
        $product1->price = 145.23;
        $product1->variant = 'Black';
        $product1->category = 'T-Shirts';

        $product2 = ProductData::createAsProductType('BLUE_T_SHIRT_981', 'Blue T-shirt');
        $product2->brand = 'Chanel';
        $product2->quantity = 1;
        $product2->price = 148.99;
        $product2->variant = 'Blue';
        $product2->category = 'T-Shirts';

        $purchaseEvent->products[] = $product1;
        $purchaseEvent->products[] = $product2;

        $purchaseEvent->applyTo($hitBuilder);
    }
}

Send hits to Google

Use a cronjob to send hits to Google regularly:

* * * * * bin/console setono:google-analytics:send-hits

No matter the interval in the cronjob, hits will never be sent before the send_delay has passed (see configuration).

FAQ

How are hit builders persisted?

When creating a hit builder using the hit builder factory, the factory will add the hit builder to the so-called hit builder stack. A response listener is then persisting the hit builders at the end of the request-response lifecycle. The same logic as the client side library is applied. This means that page views are persisted when the HTTP status code is one of 2xx, 4xx, or 5xx. All events are persisted no matter what, though. You can see this logic here.

Do I have to populate request/response parameters?

No. Out of the box, hit builders are populated with request and response parameters, i.e. the url, user agent, document title etc.

setono / google-analytics-server-side-tracking-bundle

Maintainers

Details