README

此库包含一个能够通过测量协议向 Google Analytics 4 发送事件的客户端。

请在使用此库时始终牢记谷歌关于当前 API 状态的警告。

警告：这是一个 alpha API，可能随时更改。在 alpha 阶段，您可能会遇到破坏性更改。使用此 API 的代码不应推送到生产环境。有关将在通用可用性发布之前解决的问题的限制，请参阅限制。

安装

通过 composer 安装此库，就像任何理智的 PHP 开发者会做的那样。

composer require bluepsyduck/ga4-measurement-protocol

使用

此库使用 PSR-17 和 PSR-18 将其自身逻辑与实际的客户端实现解耦。为了使用此库，必须提供兼容的实现。

以下示例展示了如何使用 guzzlehttp/guzzle 包与客户端类一起使用

<?php

use BluePsyduck\Ga4MeasurementProtocol\Config;
use BluePsyduck\Ga4MeasurementProtocol\Client;
use BluePsyduck\Ga4MeasurementProtocol\Serializer\Serializer;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Psr\Http\Client\ClientExceptionInterface;

// Create the required dependencies
$guzzleClient = new GuzzleClient();
$httpFactory = new HttpFactory();
$serializer = new Serializer();

// Create the additional config required by the client
$config = new Config();
$config->apiSecret = '1234567890abcdefghijkl';
$config->measurementId = 'G-1234567890';

// Create the actual client
$client = new Client(
    $guzzleClient, // Implementation of the PSR-18 ClientInterface 
    $httpFactory,  // Implementation of the PSR-17 RequestFactoryInterface
    $httpFactory,  // Implementation of the PSR-17 StreamFactoryInterface
    $serializer,   // Shipped with the library
    $config,
);

// Send a payload to GA4
try {
    $client->send($payload);
} catch (ClientExceptionInterface $e) {
    // Handle the exception, or ignore it
}

预定义事件

库包含表示 Google 文档 中指定的事件的类。这些类使用公共属性和类型提示来确保基本数据兼容性。库不包含任何额外的数据验证，以使其尽可能小。

以下是使用预定义事件构建实际有效载荷的示例

<?php
use BluePsyduck\Ga4MeasurementProtocol\Request\Payload;
use BluePsyduck\Ga4MeasurementProtocol\Request\Event\EarnVirtualCurrencyEvent;
use Psr\Http\Client\ClientExceptionInterface;

// Create the first simple event
$event1 = new EarnVirtualCurrencyEvent();
$event1->virtualCurrencyName = 'Gems';
$event1->value = 42;

// Create the second event, containing an item
$item = new Item();
$item->quantity = 4;
$item->itemId = 'I_12345';

$event2 = new AddPaymentInfoEvent();
$event2->value = 13.37;
$event2->currency = 'EUR';
$event2->items[] = $item;

// Create the actual payload
$payload = new Payload();
$payload->clientId = 'foo';
$payload->events = [$event1, $event2];

// Send the payload to GA4
try {
    $client->send($payload);
} catch (ClientExceptionInterface $e) {
    // Handle the exception, or ignore it
}

库认为事件的全部属性都是可选的，并用 null 初始化。请参阅参考文档以获取有关哪些属性可能实际需要设置的更多信息。

自定义事件

要创建自己的事件，只需实现 EventInterface 并将 Event 属性添加到指定事件名称的类中，以及将 Parameter 属性添加到应发送到 Google Analytics 的每个属性中。

<?php

use BluePsyduck\Ga4MeasurementProtocol\Attribute\Event;
use BluePsyduck\Ga4MeasurementProtocol\Attribute\Parameter;
use BluePsyduck\Ga4MeasurementProtocol\Request\Event\EventInterface;

#[Event('fancy_event')] // Expects the name of the event to be used in the payload to Google Analytics. 
class FancyEvent implements EventInterface
{
    /**
     * A fancy value for the fancy event.
     * @var string|null 
     */
    #[Parameter('fancy_value')] // Expects the name of the parameter to be used in the payload. Please pay attention
                                // to the limitations of parameter names, such as their maximum length.
    public ?string $fancyValue = null;
}

// Create your custom event
$fancyEvent = new FancyEvent();
$fancyEvent->fancyValue = 'fancy';

// Add the event to the payload
$payload->events[] = $fancyEvent;

必须在有效载荷中出现的所有参数都必须标记为 Parameter 或 ParameterArray 属性。建议将所有参数的默认值设置为 null，因为它们将被过滤掉，不会出现在有效载荷中。

进一步阅读

• 测量协议（Google Analytics 4）
• 参考：事件