README

概述

这是一个PHP库，用于简化Google Analytics 4（GA4）度量协议的使用。度量协议允许开发者从服务器端PHP直接向Google Analytics发送事件。

完整文档请参考此处： https://developers.google.com/analytics/devguides/collection/protocol/ga4

要求

PHP >= 7.1
ext-json
guzzlehttp/guzzle: ^6.5.5 || ^7.0.0

dev

phpunit/phpunit: "^9.5"
fakerphp/faker: "^1.14"

安装

推荐通过Composer（packagist包：br33f/php-ga4-mp）安装此库。

通过composer命令

composer require br33f/php-ga4-mp

或 package.json

{
    "require": {
        "br33f/php-ga4-mp": "^0.1.0"
    }
}

使用方法

发送商品查看事件

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\ViewItemEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET');
$ga4Service->setMeasurementId('MEASUREMENT_ID');

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setClientId('CLIENT_ID');

// Create Event Data
$viewItemEventData = new ViewItemEvent();
$viewItemEventData
    ->setValue(51.10)
    ->setCurrency('EUR');

// Create Item
$viewedItem = new ItemParameter();
$viewedItem
    ->setItemId('ITEM_ID')
    ->setItemName('ITEM_NAME')
    ->setPrice(25.55)
    ->setQuantity(2);

// Add this item to viewItemEventData
$viewItemEventData->addItem($viewedItem);

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($viewItemEventData);

// We have all the data we need. Just send the request.
$ga4Service->send($baseRequest);

发送购买事件

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\PurchaseEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET');
$ga4Service->setMeasurementId('MEASUREMENT_ID');

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setClientId('CLIENT_ID');

// Create Event Data
$purchaseEventData = new PurchaseEvent();
$purchaseEventData
    ->setValue(250.00)
    ->setCurrency('USD');

// Create Item
$purchasedItem1 = new ItemParameter();
$purchasedItem1
    ->setItemId('FIRST_ITEM_ID')
    ->setItemName('FIRST_ITEM_NAME')
    ->setPrice(100.00)
    ->setQuantity(2);

// Add this item to purchaseEventData
$purchaseEventData->addItem($purchasedItem1);

// You can also fill item data via constructor
$purchaseEventData->addItem(new ItemParameter([
    'item_id' => 'SECOND_ITEM_ID',
    'item_name' => 'SECOND_ITEM_NAME',
    'price' => 50.00,
    'quantity' => 1
]));

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($purchaseEventData);

// We have all the data we need. Just send the request.
$ga4Service->send($baseRequest);

目前，库中包含以下事件的定义结构

这些事件以类似上述示例的方式发送。

其他事件

要发送任何事件，可以使用BaseEvent结构并添加任何数据。请注意，如果已经定义了特定事件结构，则应使用该结构，因为BaseEvent不强制任何结构或提供数据验证。

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\BaseEvent;

// Create Service and request same as above
// ...

// Create Base Event Data (for example: 'share' event - https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#share)
$eventName = 'share';
$anyEventData = new BaseEvent($eventName);
$anyEventData
    ->setMethod('Twitter')
    ->setContentType('Post')
    ->setItemId('example_item_id')
    ->setAnyParamYouWish('test'); // means 'any_param_you_wish' is set


// Add event to base request (you can add up to 25 events to single request) and send, same as above
// ...

Firebase支持

可以使用此库发送Firebase事件。为此，只需像以下示例那样初始化Service和BaseRequest

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET');
$ga4Service->setFirebaseId('FIREBASE_APP_ID'); // instead of setMeasurementId(...)

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setAppInstanceId('APP_INSTANCE_ID'); // instead of setClientId(...)

同意模式v2

此库支持v2同意模式：查看文档

use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Common\ConsentProperty;
use Br33f\Ga4\MeasurementProtocol\Enum\ConsentCode;

// Create consent property with :
// - ad_user_data = GRANTED
// - ad_personalization = DENIED
$consent = new ConsentProperty();
$consent->setAdUserData(ConsentCode::GRANTED);
$consent->setAdPersonalization(ConsentCode::DENIED);

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setConsent($consent);

此模式现在取代了已过时的/废弃的non_personalized_ads

$baseRequest = new BaseRequest();
$baseRequest->setNonPersonalizedAds(true);

// Is replaced by :

$consent = new ConsentProperty();
$consent->setAdPersonalization(ConsentCode::GRANTED);
$baseRequest->setConsent($consent);

调试事件数据和请求

由于Google Analytics 4度量协议的默认端点不返回任何HTTP错误代码或消息，因此可以通过将事件发送到调试端点（度量协议验证服务器）来调试事件数据。为了验证事件，应使用sendDebug($request)方法代替send($request)。

sendDebug($request)方法返回DebugResponse对象，其中包含响应数据，例如：status_code和validation_messages。

示例

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\AddToCartEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET');
$ga4Service->setMeasurementId('MEASUREMENT_ID');

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setClientId('CLIENT_ID');

// Create Invalid Event Data
$addToCartEventData = new AddToCartEvent();
$addToCartEventData
    ->setValue(99.99)
    ->setCurrency('SOME_INVALID_CURRENCY_CODE'); // invalid currency code

// addItem
$addToCartEventData->addItem(new ItemParameter([
    'item_id' => 'ITEM_ID',
    'item_name' => 'ITEM_NAME',
    'price' => 99.99,
    'quantity' => 1
]));

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($addToCartEventData);

// Instead of sending data to production Measurement Protocol endpoint
// $ga4Service->send($baseRequest);
// Send data to validation endpoint, which responds with status cude and validation messages.
$debugResponse = $ga4Service->sendDebug($baseRequest);

// Now debug response contains status code, and validation messages if request is invalid
var_dump($debugResponse->getStatusCode());
var_dump($debugResponse->getValidationMessages());

以流的形式获取响应

可以以流的形式获取响应。当您希望进一步处理响应而不希望在BaseResponse中消耗流时，这非常有用。

sendStream($request)方法返回StreamResponse对象，其中包含响应数据，例如：status_code（就像通常一样）和body，它是一个流资源。

示例

use Br33f\Ga4\MeasurementProtocol\Service;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\AddToCartEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;

// Create service instance
$ga4Service = new Service('MEASUREMENT_PROTOCOL_API_SECRET');
$ga4Service->setMeasurementId('MEASUREMENT_ID');

// Create base request
$baseRequest = new BaseRequest();
$baseRequest->setClientId('CLIENT_ID');

// Create Invalid Event Data
$addToCartEventData = new AddToCartEvent();
$addToCartEventData
    ->setValue(99.99)
    ->setCurrency('SOME_INVALID_CURRENCY_CODE'); // invalid currency code

// addItem
$addToCartEventData->addItem(new ItemParameter([
    'item_id' => 'ITEM_ID',
    'item_name' => 'ITEM_NAME',
    'price' => 99.99,
    'quantity' => 1
]));

// Add event to base request (you can add up to 25 events to single request)
$baseRequest->addEvent($addToCartEventData);

// Instead of $ga4Service->send($baseRequest);
// That way we can get response as stream in StreamResponse class body property
$streamResponse = $ga4Service->sendStream($baseRequest);

var_dump($debugResponse->getBody());

单元测试

此模块的单元测试使用PHPUnit 9执行。

运行单元测试

composer install
php vendor/bin/phpunit

许可证

此库采用MIT许可证发布。

br33f / php-ga4-mp

维护者

详细信息