本陶/bento-php-sdk

🍱 Bento PHP SDK 和跟踪库

维护者

详细信息

github.com/bentonow/bento-php-sdk

源代码

问题

安装数: 45 279

依赖项: 0

建议者: 0

安全: 0

星标: 7

关注者: 4

分支: 6

公开问题: 0

v2.0.1.1 2024-09-20 00:13 UTC

Requires

Requires (Dev)

MIT 654fc40e4ebfdf7fde11de3c0998165491344fe0

  • Arve Solland <arvesolland.woop@gmail.com>
  • Jacob Foster <me.woop@jacob-foster.com>

This package is auto-updated.

Last update: 2024-09-20 00:13:47 UTC

README

🍱 为 PHP（和 Laravel）项目提供简单强大的分析！

在 PHP 中跟踪事件、更新数据、记录 LTV 等操作。数据存储在您的 Bento 账户中，因此您可以轻松地进行研究和调查。

👋 要获得个性化支持，请 tweet @bento 或发送电子邮件至 jesse@bentonow.com！

❤️ 感谢来自 GuitarCreative 的 @cavel（在 Discord 上）对 Laravel 文档的贡献。

安装

在您的项目文件夹中运行以下命令。（注意，此项目需要 Composer）

composer require bentonow/bento-php-sdk

安装 Laravel

如果您希望在整个应用程序中访问 Bento 实例，您可能需要考虑使用 Service Provider。在 Laravel 中，Service Providers 是启动所有框架各种组件（如路由、事件等）的关键。以下是一个基本指南

步骤 1：创建一个新的 Service Provider

您可以使用 artisan 命令生成一个新的 Service Provider

php artisan make:provider BentoServiceProvider

这将创建一个新文件在 app/Providers。

步骤 2：在新提供者中注册服务

打开新创建的提供者文件。在 register 方法中，将 Bento 实例绑定到服务容器。register 方法是绑定项到服务容器的完美位置

// Add this at the top of the file
use bentonow\Bento\BentoAnalytics;

public function register()
{
    $this->app->singleton(BentoAnalytics::class, function ($app) {
        return new BentoAnalytics([
            'authentication' => [
                'secretKey' => env('BENTO_SECRET_KEY'),
                'publishableKey' => env('BENTO_PUBLISHABLE_KEY')
            ],
            'siteUuid' => env('BENTO_SITE_UUID')
        ]);
    });
}

注意，使用 env() 函数从您的环境变量中获取值。将 'BENTO_SECRET_KEY'、'BENTO_PUBLISHABLE_KEY' 和 'BENTO_SITE_UUID' 替换为您实际的环境变量名称。

步骤 3：注册 Service Provider

在 config/app.php 中，将您的新提供者添加到 providers 数组中

'providers' => [
    // Other Service Providers

    App\Providers\BentoServiceProvider::class,
],

现在，您可以在应用程序的任何位置使用依赖注入或 app() 辅助函数从服务容器中解析（或“获取”）Bento 实例

$bento = app(BentoAnalytics::class);

或者您也可以在控制器方法中使用依赖注入

public function someMethod(BentoAnalytics $bento) 
{
    // Use $bento here...
}

这种方式，您遵循了依赖倒置原则，这是面向对象设计中的SOLID原则之一，可以使代码更易于维护和灵活。

开始使用

要开始在Bento中跟踪事物，只需初始化客户端并尽情使用！

use bentonow\Bento\BentoAnalytics;

// 1. Create the Bento client.
$bento = new BentoAnalytics([
  'authentication' => [
    'secretKey' => 'secretKey',
    'publishableKey' => 'publishableKey'
  ],
  'siteUuid' => 'siteUuid'
])

# Send in a custom event that can trigger an automation — this will also create the user in your account, no need for a second call!
# We strongly recommend using track() for most real-time things.
$bento->V1->track([
  'email' => 'test@bentonow.com',
  'type' => '$signed_up',
  'details' => [
    'fromCustomEvent' => true
  ]
]);

// Track a custom unique event (purchase, sale, etc).
$bento->V1->trackPurchase([
  'email' => 'test@bentonow.com',
  'purchaseDetails' => [
    'unique' => [
      'key' => 1234,
    ],
    'value' => [
      'amount' => 100,
      'currency' => 'USD',
    ],
    'cart' => [
      'abandoned_checkout_url' => ''
    ]
  ]
])

继续阅读，了解您可以使用SDK做什么。

模块

除了顶级的Analytics对象之外，我们还提供对API其他部分的访问，这些部分位于相应的模块之后。您可以从主Analytics对象访问这些模块。

Analytics模块还提供了对API各种版本的访问（目前仅为V1），每个版本都提供了访问以下文档中记录的相应模块的权限。

分析（基础模块）

tagSubscriber(parameters: TagSubscriberParameters): boolean

这会触发自动化！ - 如果您不想触发自动化，请使用Commands.addTag方法。

使用指定的电子邮件和标签标记订阅者。如果标签或用户不存在，它们将在系统中创建。如果用户已经有该标签，则将发送另一个标签事件，触发将标签添加到订阅者时发生的任何自动化。请注意潜在后果。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：TagSubscriberParameters

$bento->V1->tagSubscriber([
  'email' => 'test@bentonow.com',
  'tagName' => 'Test Tag',
]);

addSubscriber(parameters: AddSubscriberParameters): boolean

这会触发自动化！ - 如果您不想触发自动化，请使用Commands.subscribe方法。

在系统中创建订阅者。如果订阅者已存在，则将发送另一个订阅事件，触发订阅时发生的任何自动化。请注意潜在后果。

您可以选择传递任何希望在创建订阅者时设置的字段。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：AddSubscriberParameters

$bento->V1->addSubscriber([
  'email' => 'test@bentonow.com'
]);

$bento->V1->addSubscriber([
  'date' => '2021-08-20T01:32:57.530Z',
  'email' => 'test@bentonow.com',
  'fields' => [
    'firstName' => 'Test',
    'lastName' => 'Subscriber'
  ]
]);

removeSubscriber(parameters: RemoveSubscriberParameters): boolean

这会触发自动化！ - 如果您不想触发自动化，请使用Commands.unsubscribe方法。

在系统中取消订阅电子邮件。如果电子邮件已被取消订阅，则将发送另一个取消订阅事件，触发取消订阅时发生的任何自动化。请注意潜在后果。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：RemoveSubscriberParameters

$bento->V1->removeSubscriber([
  'email' => 'test@bentonow.com'
]);

updateFields(parameters: UpdateFieldsParameters): boolean

这会触发自动化！ - 没有方法可以不触发自动化实现相同的行为。

为订阅者设置传入的自定义字段，如果不存在则创建订阅者。如果字段已经在订阅者上设置，则将发送事件，触发字段更新时发生的任何自动化。请注意潜在后果。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：UpdateFieldsParameters

$bento->V1->updateFields([
  'email' => 'test@bentonow.com',
  'fields' => [
    'firstName' => 'Test',
  ]
]);

trackPurchase(parameters: TrackPurchaseParameters): boolean

这会触发自动化！ - 没有方法可以不触发自动化实现相同的行为。

在Bento中跟踪购买，用于计算订阅者的LTV。接收到的值应该是数字，以分表示。例如，$1.00应该是100。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：TrackPurchaseParameters

$bento->V1->trackPurchase([
  'email' => 'test@bentonow.com',
  'purchaseDetails' => [
    'unique' => [
      'key' => 1234
    ],
    'value' => [
      'amount' => 100,
      'currency' => 'USD'
    ]
  ]
]);

track(parameters: TrackParameters): boolean

这会触发自动化！ - 没有方法可以不触发自动化实现相同的行为。

在Bento中跟踪自定义事件。

因为此方法使用批量API，所以标签可能需要1到3分钟才能出现在系统中。

如果事件成功发送，则返回true。否则返回false。

参考类型：TrackParameters

$bento->V1->track([
  'email' => 'test@bentonow.com',
  'type' => '$custom.event',
  'details' => [
    'fromCustomEvent' => true
  ]
]);

批量

Batch.importSubscribers(parameters: BatchImportSubscribersParameter): number

这不会触发自动化操作！ - 如果您希望触发自动化操作，请批量导入事件，类型设置为 BentoEvents.SUBSCRIBE 或 $subscribe。请注意，批量事件导入无法附加自定义字段，并且将忽略除电子邮件外的所有内容。

创建批量作业以将订阅者导入系统。您可以导入1到1,000个订阅者。每个订阅者必须有一个电子邮件地址，并且可以可选地有其他字段。这些附加字段将作为自定义字段添加到订阅者上。

此方法由Bento导入队列处理，结果可能需要1到5分钟才能出现在您的仪表板上。

返回导入的订阅者数量。

参考类型： BatchImportSubscribersParameter

$bento->V1->Batch->importSubscribers([
  'subscribers' => [
    ['email' => 'test@bentonow.com', 'age' => 21],
    ['email' => 'test2@bentonow.com'],
    ['email' => 'test3@bentonow.com', 'name' => 'Test User']
  ]
]);

Batch.importEvents(parameters: BatchImportEventsParameter): number

创建批量作业以将事件导入系统。您可以导入1到1,000个事件。每个事件必须有一个电子邮件和一个类型。除了这些之外，您还可以在details属性中传递其他数据。

返回导入的事件数量。

参考类型： BatchImportEventsParameter

use bentonow\Bento\SDK\Batch\BentoEvents;

$bento->V1->Batch->importEvents([
  'events' => [
    ['email' => 'test@bentonow.com', 'type' => BentoEvents::SUBSCRIBE],
    ['email' => 'test@bentonow.com', 'type' => BentoEvents::UNSUBSCRIBE],
    [
      'email' => 'test@bentonow.com',
      'details' => [
        'customData' => 'Used internally.'
      ],
      'type' => '$custom.myEvent'
    ]
  ]
]);

命令

Commands.addTag(parameters: AddTagParameters): Subscriber | null

这不会触发自动化操作！ - 如果您希望触发自动化操作，请使用核心模块的 tagSubscriber 方法。

向具有匹配电子邮件的订阅者添加标签。

请注意，如果标签或订阅者中缺少任何一个，它们都将被创建。

参考类型： AddTagParameters，Subscriber

$bento->V1->Commands->addTag([
  'email' => 'test@bentonow.com',
  'tagName' => 'Test Tag'
]);

Commands.removeTag(parameters: RemoveTagParameters): Subscriber | null

从具有匹配电子邮件的订阅者中删除指定的标签。

参考类型： RemoveTagParameters，Subscriber

$bento->V1->Commands->removeTag([
  'email' => 'test@bentonow.com',
  'tagName' => 'Test Tag'
]);

Commands.addField(parameters: AddFieldParameters): Subscriber | null

这不会触发自动化操作！ - 如果您希望触发自动化操作，请使用核心模块的 updateFields 方法。

向具有匹配电子邮件的订阅者添加字段。

请注意，如果字段或订阅者中缺少任何一个，它们都将被创建。

参考类型： AddFieldParameters，Subscriber

$bento->V1->Commands->addField([
  'email' => 'test@bentonow.com',
  'field' => [
    'key' => 'testKey',
    'value' => 'testValue'
  ]
]);

Commands.removeField(parameters: RemoveFieldParameters): Subscriber | null

从具有匹配电子邮件的订阅者中删除字段。

参考类型： RemoveFieldParameters，Subscriber

$bento->V1->Commands->removeField([
  'email' => 'test@bentonow.com',
  'fieldName' => 'testField'
]);

Commands.subscribe(parameters: SubscribeParameters): Subscriber | null

这不会触发自动化操作！ - 如果您希望触发自动化操作，请使用核心模块的 addSubscriber 方法。

将提供的电子邮件订阅到Bento。如果该电子邮件不存在，则会创建。

如果订阅者之前已经取消订阅，他们将重新订阅。

参考类型： SubscribeParameters，Subscriber

$bento->V1->Commands->subscribe([
  'email' => 'test@bentonow.com'
]);

Commands.unsubscribe(parameters: UnsubscribeParameters): Subscriber | null

这不会触发自动化操作！ - 如果您希望触发自动化操作，请使用核心模块的 removeSubscriber 方法。

从Bento取消提供的电子邮件订阅。如果该电子邮件不存在，则会创建并立即取消订阅。如果他们已经取消订阅，则更新unsubscribed_at属性。

参考类型： UnsubscribeParameters，Subscriber

$bento->V1->Commands->unsubscribe([
  'email' => 'test@bentonow.com',
]);

事件

Events.createEvent(parameters: CreateEventParameters): Events[] | null

在Bento中创建一个事件。

引用类型： 事件

$bento->V1->Events->createEvent([
  'type' => '$completed_onboarding',
  'email' => 'test@test.com'
]);

实验性

Experimental.validateEmail(parameters: ValidateEmailParameters): boolean

实验性 - 此功能是实验性的，可能随时更改或停止工作。

尝试验证电子邮件。您可以提供更多信息以进一步细化验证。

如果提供了名称，它将与之比较美国人口普查数据，因此结果可能存在偏见。

引用类型： ValidateEmailParameters

$bento->V1->Experimental->validateEmail([
  'email' => 'test@bentonow.com',
]);

Experimental.guessGender(parameters: GuessGenderParameters): GuessGenderResponse

实验性 - 此功能是实验性的，可能随时更改或停止工作。

尝试根据提供的名称猜测人的性别。它将名称与美国人口普查数据进行比较，因此结果可能存在偏见。

如果系统不能自信地判断性别，则性别可能未知。

引用类型： GuessGenderParameters，GuessGenderResponse

$bento->V1->Experimental->guessGender([
  'name' => 'Jesse',
]);

Experimental.geolocate(parameters: GeolocateParameters): LocationData | null

实验性 - 此功能是实验性的，可能随时更改或停止工作。

尝试根据提供的IP地址提供位置数据。

引用类型： GeolocateParameters，LocationData

$bento->V1->Experimental->geolocate([
  'ip' => '127.0.0.1',
]);

Experimental.checkBlacklist(parameters: BlacklistParameters): BlacklistResponse

实验性 - 此功能是实验性的，可能随时更改或停止工作。

将提供的URL或IP地址与各种黑名单进行比较，以查看网站是否被任何地方列入黑名单。

引用类型： BlacklistParameters，BlacklistResponse

$bento->V1->Experimental->checkBlacklist([
  'domain' => 'bentonow.com',
]);

字段

Fields.getFields(): Field[] | null

返回网站的全部字段。

引用类型： Field

$bento->V1->Fields->getFields();

Fields.createField(parameters: CreateFieldParameters): Field[] | null

在Bento中创建一个字段。字段的名称在创建时自动从传入的键生成。例如

引用类型： CreateFieldParameters，Field

$bento->V1->Fields->createField([
  'key' => 'testKey'
]);

表单

Forms.getResponses(formIdentifier: string): FormResponse[] | null

返回具有指定标识符的表单的全部响应。

引用类型： FormResponse

$bento->V1->Forms->getResponses('test-formid-1234');

订阅者

Subscribers.getSubscribers(parameters?: GetSubscribersParameters): Subscriber | null

返回具有指定电子邮件或UUID的订阅者。

引用类型： GetSubscribersParameters，Subscriber

$bento->V1->Subscribers->getSubscribers([
  'uuid' => '1234'
]);

$bento->V1->Subscribers->getSubscribers([
  'email' => 'test@bentonow.com'
]);

Subscribers.createSubscriber(parameters: CreateSubscriberParameters): Subscriber | null

在Bento中创建一个订阅者。

引用类型： CreateSubscriberParameters，Subscriber

$bento->V1->Subscribers->createSubscriber([
  'email' => 'test@bentonow.com'
]);

标签

Tags.getTags(): Tag[] | null

返回网站的全部字段。

引用类型： Tag

$bento->V1->Tags->getTags();

Tags.createTag(parameters: CreateTagParameters): Tag[] | null

在Bento中创建一个标签。

引用类型： Tag

$bento->V1->Tags->createTag([
  'name' => 'test tag'
]);

类型参考

AddFieldParameters

AddSubscriberParameters

AddTagParameters

BatchImportEventsParameter

BatchImportSubscribersParameter

BentoEvent

此类型是几种不同类型的区分联合。以下将分别介绍这些类型。

BaseEvent

PurchaseEvent

SubscribeEvent

TagEvent

UnsubscribeEvent

UpdateFieldsEvent

BlacklistParameters

请注意，此参数要么是domain，要么是ip，但不能同时是两者。

BlacklistResponse

结果是一个对象，键是已检查的黑名单的名称，值是该域名/IP是否出现在该黑名单上。

BrowserData

CreateFieldParameters

创建订阅者参数

创建标签参数

事件

实体类型

这是一个枚举，具有以下值

字段

字段属性

表单响应

表单响应属性

表单响应数据

获取订阅者参数

注意，这可以接受 email 或 uuid，但不能同时接受两者。

地理位置参数

猜测性别参数

猜测性别响应

身份数据

位置数据

页面数据

购物车

购买详情

购买项目

除了以下属性外，您还可以传递任何其他您希望作为 PurchaseItem 部分的属性。

移除字段参数

移除订阅者参数

移除标签参数

订阅参数

订阅者

订阅者属性

标签

标签属性

标签订阅者参数

跟踪参数

跟踪购买参数

退订参数

更新字段参数

验证电子邮件参数

注意事项

  1. 跟踪：所有事件都必须被识别。匿名支持即将推出！
  2. 跟踪：大多数事件在几秒钟内被 Bento 索引。
  3. 如果您需要支持，请告诉我们！

贡献

欢迎在 GitHub 上提交错误报告和拉取请求：https://github.com/bentonow/bento-php-sdk。本项目旨在成为一个安全、友好的协作空间，贡献者应遵守贡献者公约行为准则。

许可

此软件包根据 MIT 许可证作为开源软件提供。