README

composer require alexwestergaard/php-ga4

欧洲 - GDPR 通知

欧盟通知称，Google Analytics 默认不符合 GDPR。这是因为前端客户端通过事件发送访客详情，如 IP 地址和设备信息。这可以通过欧洲区域内的一个中间人服务器来避免。

来源：欧洲，GDPR，Schrems II
选项： Google Analytics 的隐私控制

入门

设置需要 测量 ID 和 API 密钥。转到管理员（左下角）-> 账户 -> 数据流 -> {您的流}。在这里，您应该在上部找到测量 ID，并在页面下方找到“测量协议的 API 密钥”，在那里您可以创建自己的 API 密钥。

转到 管理员（左下角），然后选择您的 账户 -> 数据流 -> 您的流。
在这里，您将找到上部的 测量-ID 和进一步下方的 测量协议的 API 密钥，在那里您可以创建自己的 API 密钥。

一旦您获得了凭证，您可以通过以下方式初始化分析

use AlexWestergaard\PhpGa4\Analytics;

$analytics = Analytics::new(
    measurement_id: 'G-XXXXXXXX',
    api_secret: 'xYzzX_xYzzXzxyZxX',
    debug: true|false #Default: False
);

数据流

服务器端标签不应替代前端客户端，并且会话初始化应通过 gtag.js 客户端进行。默认流程应如下进行

获取适当的 GDPR 同意
客户端/GTAG.js 与 Google Analytics 初始化会话
Google Analytics 向客户端/GTAG.js 发送 _ga 和 _gid Cookie
服务器使用 _ga（或 _gid）发送/填充事件
- 例如：生成潜在客户、购买、退款和其他后端处理的事件。

注意：在不从 Google Analytics 获取会话 Cookie 的情况下推送事件到后端是完全可能的；但是，如果您不知道如何通过后端推送，那么您将失去 GTAG.js 请求中捆绑的信息。您可以使用自己唯一生成的 ID 替换 _ga 和 _gid 会话。

所有请求都应遵循此结构，并至少包含一个事件，以便 Google Analytics 能够接受它。

Analytics [
    Events [
        Event {
            Parameters
            ? Items [
                Item Parameters
            ]
        }
    ]
    User Properties [
        Properties {
            Key: Value
        }
    ]
    ? Consent {
      Key: Value
    }
    ? User Data {
      Key: Value
    }
]

事件

这是一份如文档中所示预构建事件的列表。所有事件都有以下参数来定位每个事件的触发位置。

// Manual setting of each event
$event->setLanguage(string $var);
$event->setPageLocation(string $var);
$event->setPageReferrer(string $var);
$event->setPageTitle(string $var);
$event->setScreenResolution(string $var);
// Fillable for multiple events
$eventPage = AlexWestergaard\PhpGa4\Helper\EventParamsHelper();
$event->setEventPage($eventPage);

默认

电子商务

参与/游戏

前端 & 后端通信

此库是为后端服务器端跟踪而构建的，但您可能将通过前端（使用 JavaScript 或 Websockets）触发大多数事件。将有 2 个示例，一个作为纯后端用于记录/排队的事件，另一个用于前端到后端的通信。

记录/队列

use AlexWestergaard\PhpGa4\Exception;
use AlexWestergaard\PhpGa4\Analytics;
use AlexWestergaard\PhpGa4\Event;
use AlexWestergaard\PhpGa4\Item;

// require vendor/autoload.php

$visitors = getVisitorsAndEvents(); // pseudo function, make your own logic here

foreach ($visitors as $collection) {
    // Group of events, perhaps need logic to change from json or array to event objects
    // Maybe its formatted well for the > ConvertHelper::parseEvents([...]) < helper
    $groups = $collection['events'];

    // If gtag.js, this can be the _ga or _gid cookie
    // This can be any kind of session identifier
    // Usually derives from $_COOKIE['_ga'] or $_COOKIE['_gid'] set by GTAG.js
    $visitor = $collection['session_id'];

    // load logged in user/visitor
    // This can be any kind of unique identifier, readable is easier for you
    // Just be wary not to use GDPR sensitive information
    $user = $collection['user_id'];

    // Render events grouped on time (max offset is 3 days from NOW)
    foreach ($groups as $time => $data) {
        try {
                $analytics = Analytics::new($measurementId, $apiSecret)
                    ->setClientId($visitor)
                    ->setTimestampMicros($time);

                if ($user !== null) {
                    $analytics->setUserId($user);
                }

                $analytics->addUserParameter(...$data['userParameters']); // pseudo logic for adding user parameters
                $analytics->addEvent(...$data['events']); // pseudo logic for adding events

                $analytics->post(); // send events to Google Analytics
        } catch (Exception\Ga4Exception $exception) {
            // Handle exception
            // Exceptions might be stacked, check: $exception->getPrevious();
        }
    }
}

前端 > 后端

前端

// array< array< eventName, array<eventParams> > >
axios.post("/your-api-endpoint/ga4-event-receiver", [
  // Note each event is its own object inside an array as
  // this allows to pass the same event type multiple times
  {
    addToCart: {
      currency: "EUR",
      value: 13.37,
      items: [
        {
          item_id: 1,
          item_name: "Cup",
          price: 13.37,
          quantity: 1,
        },
      ],
    },
  },
]);

后端

use AlexWestergaard\PhpGa4\Helper\ConvertHelper;
use AlexWestergaard\PhpGa4\Exception;
use AlexWestergaard\PhpGa4\Analytics;
use AlexWestergaard\PhpGa4\Event;

// require vendor/autoload.php

try {
    $events = ConvertHelper::parseEvents($_POST);

    Analytics::new($measurementId, $apiSecret)
        ->addEvent(...$events)
        ->post();
} catch (Exception\Ga4Exception $exception) {
    // Handle exception
    // Exceptions might be stacked, check: $exception->getPrevious();
}

自定义事件

您可以构建自己的自定义事件。您需要做的只是实现和满足 AlexWestergaard\PhpGa4\Facade\Type\EventType 外观/接口。如果您想要简化生活功能，则可以从 AlexWestergaard\PhpGa4\Helper\EventHelper 扩展您的事件，并根据需要进行覆盖。

// EventHelper implements AlexWestergaard\PhpGa4\Facade\Type\EventType
class ExampleEvent extends AlexWestergaard\PhpGa4\Helper\EventHelper
{
    // variables should be nullable as unset() will set variable as null
    protected null|mixed $my_variable;
    protected null|mixed $my_required_variable;

    // Arrays should always be instanciated empty
    protected array $my_array = [];

    public function getName(): string
    {
        return 'example_event';
    }

    public function getParams(): array
    {
        return [
            'my_variable',
            'my_array',
        ];
    }

    public function getRequiredParams(): array
    {
        return [
            'my_required_variable',
        ];
    }

    public function setMyVariable(string $value)
    {
        $this->my_variable = $value;
        return $this; // Allows chained events
    }

    public function setMyRequiredVariable(string $value)
    {
        $this->my_required_variable = $value;
        return $this; // Allows chained events
    }
}

调试

GA4 的测量协议具有调试功能，可以通过在分析构造函数中的 debug 参数中启用。

$analytics = Analytics::new(
    measurement_id: 'G-XXXXXXXX',
    api_secret: 'xYzzX_xYzzXzxyZxX',
    debug: true // default: false
);

当 Debug 启用时，事件将发送到 https://#/debug/mp/collect，其中将捕获问题，这些问题将以 GA4Exception（注意 $exception->getPrevious() 栈）的形式出现；这样的响应将如下所示

{
  "validationMessages": [
    {
      "fieldPath": "events",
      "description": "Event at index: [0] has invalid name [_badEventName]. Names must start with an alphabetic character.",
      "validationCode": "NAME_INVALID"
    }
  ]
}

通知：此库已验证在添加到分析时事件格式是否正确（$analytics->addEvent(...)）。

两个重要点

发送到验证服务器的活动不会在报告中显示。
通过测量协议（服务器端）发送的事件无法在Google Analytics管理员中的debugView中显示。

附加信息

地理位置信息仅通过从gtag、Google Tag Manager或Google Analytics for Firebase自动收集获得。
page_view事件可以工作，但在官方文档中没有记录，因此不要依赖于它。

alexwestergaard / php-ga4

维护者

详细信息