README

Snowplow Tracker

原始Snowplow Tracker的替代品。

此跟踪器提供

面向对象的API进行事件跟踪
扩展点以集成您自己的领域逻辑
抽象以交换依赖项

安装

composer require tijmenwierenga/snowplow-tracker

设置

通过提供发射器和可选的附加配置，Snowplow Tracker可以被实例化。目前，只有一个发射器可用：HttpClientEmitter。

HttpClientEmitter

The HttpClientEmitter 通过HTTP将有效载荷发送到收集器。如果您想使用此发射器，需要安装一个符合 PSR-7、PSR-17 和 PSR-18 的实现。

流行的PSR-18兼容HTTP客户端有

流行的PSR-7兼容库有

默认情况下，php-http/discovery 会发现已安装的HTTP客户端和请求工厂，因此无需额外的配置。如果您想自己配置HTTP客户端，可以传递自己的配置。同样适用于请求工厂。

使用自动发现

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Tracker;
use TijmenWierenga\SnowplowTracker\Emitters\HttpClientEmitter;

$emitter = new HttpClientEmitter('https://your-collector-uri')
$tracker = new Tracker($emitter)

不使用自动发现（使用Symfony的HTTP客户端）

<?php

declare(strict_types=1);

use Symfony\Component\HttpClient\Psr18Client;
use TijmenWierenga\SnowplowTracker\Emitters\HttpClientEmitter;
use TijmenWierenga\SnowplowTracker\Tracker;

// Instantiate your own HTTP Client
$httpClient = new Psr18Client();

// Pass it to the emitter
$emitter = new HttpClientEmitter('https://your-collector-uri', $httpClient);
$tracker = new Tracker($emitter);

跟踪器配置

为了自定义跟踪器的配置，您可以传递一个额外的配置对象

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Tracker;
use TijmenWierenga\SnowplowTracker\Config\Platform;
use TijmenWierenga\SnowplowTracker\Config\TrackerConfig;

$config = new TrackerConfig(
    Platform::WEB, // The platform you're sending events from
    'My Tracker Name', // The name of your tracker
    'my-app-id' // A unique identifier for your app
);
$tracker = new Tracker(config: $config);

处理失败

每当发射事件失败时，您不想丢失数据。因此，存在一个 TijmenWierenga\SnowplowTracker\Emitters\FallbackStrategy 来帮助您从失败中恢复。

当抛出 TijmenWierenga\SnowplowTracker\Emitters\FailedToEmit 异常时，会调用 FallbackStrategy。默认情况下，使用空的回退策略，这意味着当事件发射失败时不会发生任何事情。建议实现自己的实现，该实现存储失败的负载，以便稍后尝试发送失败的事件。

将回退策略作为 Tracker 构造函数的参数配置

<?php

declare(strict_types=1);

$fallbackStrategy = new MyFallbackStrategy();
$tracker = new Tracker(fallbackStrategy: $fallbackStrategy);

如果抛出 FailedToEmit 异常，则 Tracker 将在调用回退策略后重新抛出异常。这可能导致客户端错误，这可能是不可取的。可以通过设置 Tracker 的构造函数参数 $throwOnError 来更改此行为

<?php

declare(strict_types=1);

$tracker = new Tracker(throwOnError: false);

请注意，如果没有足够的回退策略，忽略异常会导致数据丢失而无人察觉。

使用方法

通过在 Tracker 实例上调用 track() 方法来跟踪事件：此库实现了6种类型的事件。

页面浏览量

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\Pageview;

$tracker->track(new Pageview(
    'https://github.com/TijmenWierenga',
    'Tijmen Wierenga (Tijmen Wierenga)',
    'https://twitter.com/TijmenWierenga'
));

页面ping

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\PagePing;

$tracker->track(new PagePing(
    0, // min horizontal offset
    500, // max horizontal offset
    250, // min vertical offset
    300 // max vertical offset
));

电子商务交易

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\EcommerceTransaction;

$tracker->track(new EcommerceTransaction(
    'd85e7b63-c046-47ac-b9a9-039d33ef3b3b', // order ID
    49.95, // total value
));

交易项

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\TransactionItem;

$tracker->track(new TransactionItem(
    'd85e7b63-c046-47ac-b9a9-039d33ef3b3b', // order ID
    '48743-48284-24', // SKU
    12.95, // price
    4 // quantity
));

结构化事件

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\StructuredEvent;

$tracker->track(new StructuredEvent(
    'my-category',
    'my-action'
));

非结构化事件

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\UnstructuredEvent;
use TijmenWierenga\SnowplowTracker\Schemas\Schema;
use TijmenWierenga\SnowplowTracker\Schemas\Version;

$tracker->track(new UnstructuredEvent(
    new Schema(
        'com.snowplowanalytics.snowplow',
        'ad_impression',
        new Version(1, 0, 0)
    ),
    [
        'impressionId' => 'dcefa2cc-9e82-4d7e-bbeb-eef0e9dad57d'
    ]
));

Snowplow Tracker协议

所有事件都扩展自一个基事件类，该类实现了当前在 Snowplow Tracker协议中可用的所有属性。这些属性在每次事件中都是公开可用的。下面的示例显示了如何向事件添加一个 userId 以识别用户

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\Pageview;

$pageviewEvent = new Pageview('https://github.com/TijmenWierenga');

$pageviewEvent->userId = 'TijmenWierenga';

自定义上下文

有时您可能想为事件添加额外的上下文。自定义上下文是自描述的JSON模式，可以通过创建一个实现了TijmenWierenga\SnowplowTracker\Events\Schemable的类来实现。以下示例展示了如何实现由Snowplow Analytics定义的现有Timing JSON模式。

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\Schemable;
use TijmenWierenga\SnowplowTracker\Schemas\Schema;
use TijmenWierenga\SnowplowTracker\Schemas\Version;

final class Timing implements Schemable
{
    public function __construct(
        private readonly string $category,
        private readonly string $variable,
        private readonly int $timing,
        private readonly ?string $label = null
    ) {
    }
    
    public function getSchema(): Schema
    {
        return new Schema(
            'com.snowplowanalytics.snowplow',
            'timing',
            new Version(1, 0, 0)
        );
    }
    
    public function getData(): array|string|int|float|bool|JsonSerializable
    {
        return array_filter([
            'category' => $this->category,
            'variable' => $this->variable,
            'timing' => $this->timing,
            'label' => $this->label
        ]);
    } 
}

例如，让我们在页面查看事件中包含有关页面加载的上下文。

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\Pageview;

$pageviewEvent = new Pageview('https://github.com/TijmenWierenga');

$pageLoad = new Timing(
    'pageLoad',
    'ms',
    21
);

$pageviewEvent->addContext($pageLoad);

中间件

中间件提供了一种对跟踪的事件进行操作的方式。每个中间件都是一个可调用的，它接收事件作为参数，并必须将（修改后的）事件返回给下一个中间件。

callable(Event $event): Event

当您想要为每个事件添加上下文信息时，这非常有用。例如，可以添加一个中间件，将当前认证用户的userId添加到事件中。

<?php

declare(strict_types=1);

use TijmenWierenga\SnowplowTracker\Events\Event;
use TijmenWierenga\SnowplowTracker\Events\Pageview;
use TijmenWierenga\SnowplowTracker\Events\StructuredEvent;
use TijmenWierenga\SnowplowTracker\Tracker;

final class AddUserIdMiddleware
{
    public function __construct(
        private readonly AuthenticatedUserIdProvider $userIdProvider
    ) {
    }
    
    public function __invoke(Event $event): Event
    {
        $event->userId = $this->userIdProvider->getUserId();
        
        return $event;
    }
}

$addUserIdMiddleware = new AddUserIdMiddleware(/** ... */);

$tracker = new Tracker(middleware: [$addUserIdMiddleware]);

$pageviewEvent = new Pageview('https://github.com/TijmenWierenga');
$structuredEvent = new StructuredEvent('my-category', 'my-action');

$tracker->track($pageviewEvent);
$tracker->track($structuredEvent);

在上面的示例中，这两个事件现在都将附加一个userId。

tijmenwierenga / snowplow-tracker

维护者

详细信息