README

使用此扩展包通过 Google Analytics 跟踪您的访客，但使用服务器端集成而不是常规的客户端集成。

此扩展包基于 Google Analytics 测量协议库，该库又基于 Google 的通用分析解决方案。当 GA4 跟踪解决方案功能完善并退出测试版时，将实现此解决方案。

安装

此扩展包还依赖于 Client Id 扩展包 和 Consent 扩展包，分别生成客户端 ID 并提供同意服务。如果您不受欧盟 Cookie 法规的约束，请查看 Consent 扩展包的 配置 以默认授予同意。

安装此扩展包，只需运行

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

这将安装扩展包，如果您使用 Symfony Flex，则会启用它。如果您不使用 Flex，请手动将扩展包添加到 bundles.php。

创建迁移

击中次数会保存到数据库中，因此您需要创建一个迁移文件

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

配置

要启用跟踪，您需要提供要跟踪的 Google Analytics 属性

# 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

如果您将属性存储在其他地方，例如数据库中，您只需实现 Setono\GoogleAnalyticsServerSideTrackingBundle\Provider\PropertyProviderInterface，它返回属性列表。

您还可以配置在向 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

用法

默认情况下，此扩展包将开始跟踪访客，就像客户端集成一样，但与客户端集成一样，您可能还想添加特定于您应用程序的定制跟踪。以下是一个电商事件 购买 的示例

<?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);
    }
}

向 Google 发送击中

使用 cron 作业定期向 Google 发送击中

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

无论 cron 作业的间隔如何，击中都不会在 send_delay 过去之前发送（请参阅 配置）。

常见问题解答

击中构建器是如何持久化的？

使用击中构建器工厂创建击中构建器时，工厂会将击中构建器添加到所谓的击中构建器堆栈中。然后，响应监听器会在请求-响应生命周期结束时持久化击中构建器。应用与客户端库相同的逻辑。这意味着当 HTTP 状态码为 2xx、4xx 或 5xx 时，将持久化页面视图。尽管如此，所有事件都会持久化。您可以在 这里 查看此逻辑。

我必须填充请求/响应参数吗？

说明。出厂时，构建器已经填充了请求和响应参数，例如 URL、用户代理、文档标题等。