README

Google Analytics 4 测量协议的 PHP 库。确保类型安全并提供使用测量协议 API 跟踪的流畅接口。

简介

这个库是 Google Analytics 4 测量协议的 PHP 实现。它提供了一种流畅的接口来跟踪事件、用户属性和用户交互。库确保类型安全并提供了一种简单的方式来发送数据到测量协议 API。

通过使用类来表示事件、用户属性和用户交互，库确保发送到 API 的数据是有效且格式正确的。这降低了错误的风险，并使跟踪事件和用户交互变得更容易。

它还通过提供简单直观的 API，使跟踪事件和用户交互变得非常容易。您可以使用简单的类和方法创建事件、用户属性和用户交互，然后通过单个方法调用将数据发送到 API，在一个请求中可以发送多个事件给同一用户！

安装

您可以通过 Composer 安装此库。运行以下命令

composer require kevinfrom/ga4mp

示例： sign_up

此示例展示了如何跟踪 sign_up 事件。

<?php

use kevinfrom\GA4MP\Events\Generic\SignUp;
use kevinfrom\GA4MP\Http\Payload;
use kevinfrom\GA4MP\Http\Client;


$signupEvent = new Signup();

// The client ID should be read from the "_ga" cookie set by GA4. Note that php does not have access to the cookies set by GA4.
$clientId = '123456789.1234567890';
$payload = new Payload($clientId, $signupEvent)

// The API secret can be created in the GA4 interface.
$apiSecret = '[API_SECRET]';
// The measurement ID can be read from the GA4 interface. 
$measurementId = 'G-xxxxxxxx';
$client = new Client($apiSecret, $measurementId);

// You should validate the payload before sending it to the API.
$validateResponse = $client->validate($payload);
if ($validateResponse->isOk()) {
    $response = $client->send($payload);
    
    if ($response->isOk() === false) {
        // Handle API errors
        $errors = $response->getData();
        // ...
    }
} else {
    // Handle validation errors
    $errors = $validateResponse->getData();
    // ...
}

事件项

一些事件，如 add_to_cart、purchase 和 view_item，需要将附加项与事件一起发送。库提供了表示这些项的类，并确保发送到 API 的数据是有效且格式正确的。

例如，要跟踪带有项目列表的 purchase 事件，您可以使用 Purchase 和 EventItem 类

<?php

use kevinfrom\GA4MP\Events\EventItem;
use kevinfrom\GA4MP\Events\Ecom\Purchase;
use kevinfrom\GA4MP\Http\Payload;
use kevinfrom\GA4MP\Http\Client;

$itemId = 'tshirt-1';
$itemName = 'White t-shirt';
$eventItem = new EventItem($itemId, $itemName);

// You can set additional properties for the item using setters
$eventItem->setItemCategory('Apparel');
$eventItem->setQuantity(3);
$eventItem->setPrice(49.95);
$eventItem->setItemVariant('White');

$value = $eventItem->getPrice() * $eventItem->getQuantity();
$currency = 'USD';
$purchaseEvent = new Purchase($value, $currency, [$eventItem]);

$payload = new Payload($clientId, $purchaseEvent)

$client = new Client($apiSecret, $measurementId);

$validateResponse = $client->validate($payload);
if ($validateResponse->isOk()) {
    $response = $client->send($payload);
    
    if ($response->isOk() === false) {
        // Handle API errors
        $errors = $response->getData();
        // ...
    }
} else {
    // Handle validation errors
    $errors = $validateResponse->getData();
    // ...
}

同意、用户地址和用户提供的资料

此库还提供了表示用户属性、用户地址和同意信息的类。这些类可用于发送有关用户的附加信息。

<?php

use kevinfrom\GA4MP\Data\Consent;
use kevinfrom\GA4MP\Data\UserProvidedData;
use kevinfrom\GA4MP\Data\UserAddress;
use kevinfrom\GA4MP\Events\Ecom\Purchase;
use kevinfrom\GA4MP\Events\EventItem;
use kevinfrom\GA4MP\Http\Payload;
use kevinfrom\GA4MP\Http\Client;

$payload = new Payload($clientId, $purchaseEvent);

// Create a Consent object and set ad user data and ad personalization
$adUserData = true;
$adPersonalization = true;
$consent = new Consent($adUserData, $adPersonalization);

$payload->setConsent($consent);

// Create a UserProvidedData object and add user provided data
$userProvidedData = new UserProvidedData();
$userProvidedData->addEmailAddress('john@doe.com');
$userProvidedData->addPhoneNumber('+1234567890');
$userAddress = new UserAddress();
$userAddress->setCountry('DK');
$userAddress->setCity('Copenhagen');
$userAddress->setPostalCode('2300');
$userProvidedData->setAddress($userAddress);

// Now set the user provided data on the payload
$payload->setUserProvidedData($userProvidedData);

$validateResponse = $client->validate($payload);
if ($validateResponse->isOk()) {
    $response = $client->send($payload);
    
    if ($response->isOk() === false) {
        // Handle API errors
        $errors = $response->getData();
        // ...
    }
} else {
    // Handle validation errors
    $errors = $validateResponse->getData();
    // ...
}

对用户提供的资料进行哈希处理

根据测量协议文档，库自动对一些用户提供的资料进行了哈希处理。

请勿自行尝试对数据进行哈希处理，因为库将为您处理。否则，数据将被哈希两次，并且数据将不匹配 GA4 中的数据。

GA4 中的 DebugView

GA4 中的 DebugView 是调试事件和用户交互的绝佳工具。它允许您实时查看发送到 API 的数据，并验证其正确性。

但是，为了正确工作，GA4 需要事先知道客户端 ID。这意味着您需要在使用测量协议 API 对该用户进行跟踪之前，先使用 gtag.js 开始跟踪。

更多详情请参阅： https://www.simoahava.com/analytics/debugview-with-ga4-measurement-protocol/

事件列表

事件列表基于 Google 的这篇文章： https://support.google.com/analytics/answer/9267735?hl=en