README

Laravel Segment 是一种有见地的集成 Segment 到 Laravel 应用程序的方法。

安装

您可以通过 composer 安装此包

composer require slashequip/laravel-segment

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="SlashEquip\LaravelSegment\LaravelSegmentServiceProvider"

这是已发布的配置文件的内容，应位于 config/segment.php

return [
    'enabled' => env('SEGMENT_ENABLED', true),

    /**
     * This is your Segment API write key. It can be
     * found under Source > Settings > Api Keys
     */
    'write_key' => env('SEGMENT_WRITE_KEY', null),

    /**
     * Should the Segment service defer all tracking
     * api calls until after the response, sending
     * everything using the bulk/batch api?
     */
    'defer' => env('SEGMENT_DEFER', false),

    /**
     * Should the Segment service be run in safe mode.
     * Safe mode will only report errors in sending
     * when safe mode is off exceptions are thrown
     */
    'safe_mode' => env('SEGMENT_SAFE_MODE', true),
];

设置您的写入密钥

您的写入密钥是 Segment 给您的 API 密钥，可以在您的 PHP 源设置下找到；在 Segment UI 中为 https://app.segment.com/{your-workspace-name}/sources/{your-source-name}/settings/keys。

Segment 用户是什么

当我们在这个包的上下文中谈论“用户”时，我们指的是任何实现了 SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment 协议的对象；该包包含一个特性（以及接口），您可以将它附加到您的默认用户模型上；

use Illuminate\Database\Eloquent\Model;
use SlashEquip\LaravelSegment\Traits\HasSegmentIdentityByKey;
use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;

class User extends Model implements CanBeIdentifiedForSegment
{
    use HasSegmentIdentityByKey;
}

使用此特性将自动使用您的用户的唯一键作为发送到 Segment 的标识符。或者，您可以在您的用户模型上实现自己的 public function getSegmentIdentifier(): string; 方法实例，而不使用特性。

全局识别用户

如果您在应用程序的多个位置以及在整个请求中发送 Segment 事件，那么全局识别用户可能会使其在执行跟踪调用时更加方便。

use SlashEquip\LaravelSegment\Facades\Segment;

Segment::setGlobalUser($user);

全局设置上下文

Segment 允许您在跟踪事件中发送上下文，您还可以设置一个适用于所有跟踪事件的全球上下文。

use SlashEquip\LaravelSegment\Facades\Segment;

Segment::setGlobalContext([
    'ip' => '127.0.0.1',
    'locale' => 'en-US',
    'screen' => [
        'height' => 1080,
        'width' => 1920,
    ],
]);

这里有一些便利之处

Laravel Segment 随带一个中间件，您可以在 HTTP Kernal 中应用它，该中间件将处理全局用户的设置和一些合理的全局上下文。如果您想添加默认上下文之外的内容，扩展此中间件并进行调整应该很简单。

    'api' => [
        // ... other middleware
        SlashEquip\LaravelSegment\Middleware\ApplySegmentGlobals::class
    ],

用法

用于跟踪事件

use SlashEquip\LaravelSegment\Facades\Segment;

Segment::forUser($user)->track('User Signed Up', [
    'source' => 'Product Hunt',
]);

// If you have set a global user you can
// use the simpler provided syntax.
Segment::track('User Signed Up', [
    'source' => 'Product Hunt',
]);

// If you have defer enabled in the config
// you can still track an event immediately using trackNow.
Segment::trackNow('User Signed Up', [
    'source' => 'Product Hunt',
]);

用于识别用户

use SlashEquip\LaravelSegment\Facades\Segment;

Segment::forUser($user)->identify([
    'last_logged_in' => '2021-03-24 20:05:30',
    'latest_subscription_amount' => '$24.60',
]);

// If you have set a global user you can
// use the simpler provided syntax.
Segment::identify([
    'last_logged_in' => '2021-03-24 20:05:30',
    'latest_subscription_amount' => '$24.60',
]);

// If you have defer enabled in the config
// you can still identify a user immediately using identifyNow.
Segment::identifyNow('User Signed Up', [
    'source' => 'Product Hunt',
]);

Laravel 通知

此包包含一个开箱即用的通知通道，允许您使用 Laravel 内置的通知功能。要将 Segment 事件作为通知发送给用户，按正常方式生成您的通知；

php artisan make:notification UserSubscribed

您必须确保您的通知实现了 CanNotifyViaSegment 接口，并添加所需的 toSegment 方法。然后您可以将 via 方法配置为包含 SegmentChannel 类。

然后您可以调整 toSegment 方法以返回您希望的事件。

use Illuminate\Notifications\Notification;
use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
use SlashEquip\LaravelSegment\Contracts\CanBeSentToSegment;
use SlashEquip\LaravelSegment\Contracts\CanNotifyViaSegment;
use SlashEquip\LaravelSegment\Notifications\SegmentChannel;
use SlashEquip\LaravelSegment\SimpleSegmentEvent;

class UserSubscribed extends Notification implements CanNotifyViaSegment
{
    public function __construct(
    ) {
    }

    public function via(object $notifiable): array
    {
        return [SegmentChannel::class];
    }

    public function toSegment(CanBeIdentifiedForSegment $notifiable): CanBeSentToSegment
    {
        return new SimpleSegmentEvent(
            $notifiable,
            'User Subscribed',
            [
                'plan' => 'basic',
                'team_name' => 'Funky chickens',
            ],
        );
    }
}

其他

延迟

当您开始在您的应用程序中触发许多事件时，即使每个请求只有 2-3 个事件，启用延迟（见配置）也会非常有用。当启用延迟时，服务将存储整个请求或过程中触发的所有跟踪事件，然后在您的应用程序响应用户后批量发送它们。这发生在 Laravel 终止期间。

安全模式

默认情况下，安全模式是开启的。当安全模式激活时，它将吞下在向 Segmenta 发出 HTTP 请求时抛出的任何异常，并自动将其报告给异常处理程序，允许您的应用程序继续运行。当禁用时，则抛出异常。

测试

./vendor/bin/pest

变更日志

请参阅变更日志获取关于最近更改的更多信息。

贡献

请参阅贡献指南获取详细信息。

安全漏洞

请审查我们的安全策略了解如何报告安全漏洞。

鸣谢

许可证

MIT 许可证 (MIT)。请参阅许可证文件获取更多信息。

slashequip / laravel-segment

维护者

详细信息