README

简化了使用 Google Analytics 4 测量协议 在 Laravel 应用程序中跟踪事件的操作。

安装

1. 通过 Composer 安装包

composer require luketowers/laravel-ga4-event-tracking

1. 在您的 .env 文件中设置 GA4_MEASUREMENT_ID 和 GA4_MEASUREMENT_PROTOCOL_API_SECRET。

分别从 Google Analytics > Admin > Data Streams > [选择站点] > Measurement ID 及 Google Analytics > Admin > Data Streams > [选择站点] > Measurement Protocol API secrets 复制。

1. 可选：通过在终端运行此命令发布配置/视图文件

php artisan vendor:publish --tag=ga4-event-tracking.config --tag=ga4-event-tracking.views

1. 在 Google Analytics 跟踪代码之后，在布局文件中包含 sendGA4ClientID 指令。

<!-- Google Analytics Code -->
@sendGA4ClientID
<!-- </head> -->

client_id 是将事件发送到 Google Analytics 所必需的。此包提供了一个 Blade 指令，您可以将它放在布局文件中 Google Analytics 代码跟踪代码之后。它从 Google Analytics 注入的 ga() 或 gtag() 辅助函数中抓取当前用户的 GA client_id，并向您的应用程序发送 POST 请求以将 client_id 存储在会话中，该会话随后由 DispatchAnalyticsJob 在将事件发送到 GA4 时使用。

如果您不使用此 blade 指令，您将不得不自己处理检索、存储和发送 client_id。您可以使用 GA$::setClientId($clientId) 手动设置 client_id。

用法

此包提供了两种将事件发送到 Google Analytics 4 的方法

直接通过 GA4 门面

直接发送事件就像在任何后端位置调用 GA4 门面上的 sendEvent($eventData) 方法一样简单，将事件发布到 Google Analytics 4。 $eventData 包含事件名称和参数，如此 参考页面 所示。例如

GA4::sendEvent([
    'name' => 'login',
    'params' => [
        'method' => 'Google',
    ],
]);

sendEvent() 方法将返回一个包含请求状态的数组。

通过 Laravel 事件系统向 GA4 广播事件

只需将 ShouldBroadcastToAnalytics 接口添加到您的事件，您就准备好了！您无需手动绑定任何监听器。

<?php

namespace App\Events;

use App\Order;
use LukeTowers\GA4EventTracking\ShouldBroadcastToAnalytics;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderWasCreated implements ShouldBroadcastToAnalytics
{
    use Dispatchable, SerializesModels;

    public $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }
}

还有一些其他方法可以让您自定义发送到 GA4 的调用。

broadcastGA4EventAs

使用此方法，您可以自定义 事件操作 的名称。默认情况下，我们使用没有命名空间的类名。此方法还让您访问底层的 GA4 类实例。

eventOccurredAt

使用此方法，您可以自定义事件发生的时间。这将用于发送到测量协议的 timestamp_micros 参数。默认情况下，我们使用当前时间。您必须返回一个 Carbon\Carbon 实例，以便它可以被使用。

use Carbon\Carbon;
use LukeTowers\GA4EventTracking\GA4;
use LukeTowers\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

使用此方法，您可以设置发送事件时的事件参数。

<?php

namespace App\Events;

use App\Order;
use LukeTowers\GA4EventTracking\ShouldBroadcastToAnalytics;
use LukeTowers\GA4EventTracking\GA4;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderWasCreated implements ShouldBroadcastToAnalytics
{
    use Dispatchable, SerializesModels;

    public $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    public function withGA4Parameters(GA4 $ga4): array
    {
        $eventData = [
            'transaction_id' => $order->id,
            'value' => $order->amount_total,
            'currency' => 'USD',
            'tax' => $order->amount_tax,
            'shipping' => $order->amount_shipping,
            'items' => [],
            'event_category' => config('app.name'),
            'event_label' => 'Order Created',
        ];

        foreach ($order->items as $item) {
            $eventData['items'][] = [
                'id' => $item->sku ?: 'p-' . $item->product->id,
                'name' => $item->title,
                'brand' => $item->product->brand->name ?? '',
                'category' => $item->product->category->title ?? '',
                'quantity' => $item->quantity,
                'price' => $item->price,
                'variant' => $item->variant->title ?? '',
            ];
        }

        return $eventData;
    }

    public function broadcastGA4EventAs(GA4 $ga4): string
    {
        return 'purchase';
    }
}

处理框架和第三方事件

如果您需要处理无法添加ShouldBroadcastToAnalytics接口的事件，您可以使用EventServiceProvider手动注册它们，使用DispatchAnalyticsJob监听器。

<?php

namespace App\Providers;

use LukeTowers\GA4EventTracking\Listeners\DispatchAnalyticsJob;
use Illuminate\Auth\Events\Registered;
use Illuminate\Auth\Listeners\SendEmailVerificationNotification;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        Registered::class => [
            SendEmailVerificationNotification::class,
            DispatchAnalyticsJob::class,
        ],
    ];
}

调试模式

您也可以通过在调用sendEvent()方法之前调用enableDebugging()方法来启用调试模式。如下所示 - GA4::enableDebugging()->sendEvent($eventData)。在这种情况下，sendEvent()方法将返回来自Google Analytics请求的响应（数组）。

测试

composer test

或者

./vendor/bin/phpunit

安全

如果您发现任何安全相关的问题，请使用报告漏洞按钮，而不是使用问题跟踪器。

致谢

此包是以下项目的分支

• protonemedia/laravel-analytics-event-tracking：原始包，但仅支持通用分析。
• daikazu/laravel-ga4-event-tracking：从原始包分支以支持Google Analytics 4，但该包未维护，且与Laravel 10不兼容。
• accexs/laravel-ga4-event-tracking：从daikazu的包分支，但缺少一些功能，且分支不干净。

许可证

此软件包是开源软件，根据MIT许可证授权。