README

PHP-библиотека для серверной отправки аналитических событий в Яндекс Метрику и Google Analytics 4 через Measurement Protocol.

Установка

composer require noith/measurement-protocol

Яндекс Метрика

Токен и ID счётчика генерируются в настройках счётчика → Загрузка данных → Measurement Protocol.

Клиент

use Noith\MeasurementProtocol\Yandex\Client;

$client = new Client(counterId: '5564333', token: 'your-secret-token');

cid (ClientID пользователя) передаётся в каждый вызов send() — он не является частью объекта запроса.

Просмотр страницы

use Noith\MeasurementProtocol\Yandex\Requests\PageViewRequest;

$client->send($cid, PageViewRequest::make([
    'dl' => 'https://example.com/product/123',
    'dr' => 'https://google.com',
    'dt' => 'Product Page',
]));

Цель (событие)

use Noith\MeasurementProtocol\Yandex\Requests\GoalRequest;

$client->send($cid, GoalRequest::make([
    'dl' => 'https://example.com/register',
    'ea' => 'registration',
]));

Ecommerce

use Noith\MeasurementProtocol\Yandex\DTO\Product;
use Noith\MeasurementProtocol\Yandex\Requests\PurchaseRequest;

$product = new Product();
$product->id = 'SKU-123';
$product->nm = 'iPhone 15';
$product->pr = 50000.0;
$product->qt = 1.0;
$product->br = 'Apple';      // опционально
$product->ca = 'Phones';     // опционально

$request = PurchaseRequest::make([
    'dl' => 'https://example.com/checkout',
    'ea' => 'purchase',
    'ti' => 'order-42',
    'tr' => '50000',
]);
$request->_pr = [$product];

$client->send($cid, $request);

Доступные ecom-события: DetailRequest, AddToCartRequest, RemoveFromCartRequest, PurchaseRequest.

Параметры визита и кастомные параметры

$request = GoalRequest::make([
    'dl'       => 'https://example.com',
    'ea'       => 'order-success',
    '_params'  => ['level1' => ['level2' => 'value']],  // параметры визита (JSON)
    '_custom'  => ['ev' => 1500.0],                     // произвольные доп. параметры
]);

Собственное событие

class RegistrationRequest extends GoalRequest
{
    public string $ea = 'registration';
}

$client->send($cid, RegistrationRequest::make(['dl' => 'https://example.com/register']));

Google Analytics 4

measurement_id и api_secret создаются в GA4 Admin → Data Streams → Measurement Protocol API secrets.

Веб-клиент

use Noith\MeasurementProtocol\GA4\Client;

$client = new Client(measurementId: 'G-XXXXXXXXXX', apiSecret: 'your-api-secret');

Мобильное приложение (Firebase)

use Noith\MeasurementProtocol\GA4\AppClient;

$client = new AppClient(firebaseAppId: '1:1234567890:android:abcdef', apiSecret: 'your-api-secret');

// Вместо clientId передаётся appInstanceId
$client->send($appInstanceId, $request);

Просмотр страницы

use Noith\MeasurementProtocol\GA4\Requests\PageViewRequest;

$client->send($clientId, PageViewRequest::make([
    'page_location' => 'https://example.com/product/123',
    'page_title'    => 'Product Page',
    'page_referrer' => 'https://google.com',
]));

Произвольное событие

use Noith\MeasurementProtocol\GA4\Requests\EventRequest;

$client->send($clientId, EventRequest::make([
    'name'   => 'sign_up',
    'params' => ['method' => 'email'],
]));

Ecommerce

use Noith\MeasurementProtocol\GA4\DTO\Item;
use Noith\MeasurementProtocol\GA4\Requests\PurchaseRequest;

$item = new Item();
$item->item_id   = 'SKU-123';
$item->item_name = 'iPhone 15';
$item->price     = 50000.0;
$item->quantity  = 1;
$item->item_brand    = 'Apple';   // опционально
$item->item_category = 'Phones';  // опционально
$item->params = ['custom_color' => 'black'];  // кастомные параметры товара

$request = PurchaseRequest::make([
    'currency'       => 'RUB',
    'value'          => 50000.0,
    'transaction_id' => 'order-42',
    'items'          => [$item],
]);

$client->send($clientId, $request);

Полный список ecom-событий: ViewItemRequest, AddToCartRequest, RemoveFromCartRequest, ViewCartRequest, BeginCheckoutRequest, AddShippingInfoRequest, AddPaymentInfoRequest, PurchaseRequest, RefundRequest.

События со списком товаров: ViewItemListRequest, SelectItemRequest.

Промо-события: ViewPromotionRequest, SelectPromotionRequest.

Контекст пользователя

use Noith\MeasurementProtocol\GA4\GA4Context;

$context = new GA4Context(
    userId: 'user-42',                               // ID авторизованного пользователя
    ipOverride: '1.2.3.4',                           // IP клиента (для серверного трекинга)
    userProperties: ['plan' => ['value' => 'pro']],  // свойства пользователя
);

$client->send($clientId, $request, $context);

Debug-режим

// Маршрутизирует запрос на /debug/mp/collect
// Возвращает JSON с описанием ошибок валидации
$client->send($clientId, $request->asDebug());

Собственное событие

use Noith\MeasurementProtocol\GA4\Requests\AbstractGA4Request;

class SignUpRequest extends AbstractGA4Request
{
    public ?string $method = null;

    protected function eventName(): string { return 'sign_up'; }

    protected function eventParams(): array
    {
        return $this->method !== null ? ['method' => $this->method] : [];
    }
}

$client->send($clientId, SignUpRequest::make(['method' => 'email']));

Laravel

Провайдер регистрируется автоматически. Опубликуйте конфиг:

php artisan vendor:publish --tag=measurement-protocol

Добавьте в .env:

YANDEX_METRICA_COUNTER_ID=5564333
YANDEX_METRICA_TOKEN=your-secret-token

GA4_MEASUREMENT_ID=G-XXXXXXXXXX
GA4_API_SECRET=your-api-secret

# Для мобильных приложений (опционально)
GA4_FIREBASE_APP_ID=1:1234567890:android:abcdef
GA4_APP_API_SECRET=your-app-api-secret

Отправка через очередь

use Noith\MeasurementProtocol\Laravel\Jobs\SendYandexEventJob;
use Noith\MeasurementProtocol\Laravel\Jobs\SendGA4EventJob;
use Noith\MeasurementProtocol\Laravel\Jobs\SendGA4AppEventJob;

// Яндекс
SendYandexEventJob::dispatch(
    cid: $user->metrica_client_id,
    request: GoalRequest::make(['dl' => $url, 'ea' => 'registration']),
);

// GA4 веб
SendGA4EventJob::dispatch(
    clientId: $user->ga4_client_id,
    request: EventRequest::make(['name' => 'sign_up', 'params' => ['method' => 'email']]),
    context: new GA4Context(userId: (string) $user->id),
);

// GA4 приложение
SendGA4AppEventJob::dispatch(
    appInstanceId: $user->firebase_instance_id,
    request: EventRequest::make(['name' => 'sign_up', 'params' => []]),
);

License

MIT. See LICENSE.