🍱 Simple, powerful analytics for PHP projects!
Track events, update data, record LTV and more in PHP. Data is stored in your Bento account so you can easily research and investigate what's going on.
👋 To get personalized support, please tweet @bento or email jesse@bentonow.com!
- Installation
- Get Started
- Modules
- Analytics (Base Module)
- tagSubscriber(parameters: TagSubscriberParameters): boolean
- addSubscriber(parameters: AddSubscriberParameters): boolean
- removeSubscriber(parameters: RemoveSubscriberParameters): boolean
- updateFields(parameters: UpdateFieldsParameters): boolean
- trackPurchase(parameters: TrackPurchaseParameters): boolean
- Batch
- Commands
- .addTag(parameters: AddTagParameters): Subscriber | null
- .removeTag(parameters: RemoveTagParameters): Subscriber | null
- .addField(parameters: AddFieldParameters): Subscriber | null
- .removeField(parameters: RemoveFieldParameters): Subscriber | null
- .subscribe(parameters: SubscribeParameters): Subscriber | null
- .unsubscribe(parameters: UnsubscribeParameters): Subscriber | null
- Experimental
- Fields
- Forms
- Subscribers
- Tags
- Analytics (Base Module)
- Types Reference
- Things to Know
- Contributing
- License
Run the following command in your project folder. (Note, this project requires Composer)
composer require bentonow/bento-php-sdk
To get started with tracking things in Bento, simply initialize the client and run wild!
use bentonow\Bento\BentoAnalytics;
// 1. Create the Bento client.
$bento = new BentoAnalytics([
'authentication' => [
'secretKey' => 'secretKey',
'publishableKey' => 'publishableKey'
],
'siteUuid' => 'siteUuid'
])
// Create a new subscriber.
$bento->V1->addSubscriber([
'email' => 'test@bentonow.com'
]);
// Update the fields on a subscriber.
$bento->V1->updateFields([
'email' => 'test@bentonow.com',
'fields' => [
'firstName' => 'Test',
'lastName' => 'User'
]
])
// Track a purchase.
$bento->V1->trackPurchase([
'email' => 'test@bentonow.com',
'purchaseDetails' => [
'unique' => [
'key' => 1234,
],
'value' => [
'amount' => 100,
'currency' => 'USD',
],
'cart' => [
'abandoned_checkout_url' => ''
]
]
])
Read on to see what all you can do with the SDK.
In addition to the top-level Analytics object, we also provide access to other parts of the API behind their corresponding modules. You can access these off of the main Analytics
object.
The Analytics
module also provides access to various versions of the API (currently just V1
), and each of those provides access to the corresponding modules documented below.
This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.addTag
method.
Tags a subscriber with the specified email and tag. If either the tag or the user do not exist, they will be created in the system. If the user already has the tag, another tag event will be sent, triggering any automations that take place upon a tag being added to a subscriber. Please be aware of the potential consequences.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: TagSubscriberParameters
$bento->V1->tagSubscriber([
'email' => 'test@bentonow.com',
'tagName' => 'Test Tag',
]);
This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.subscribe
method.
Creates a subscriber in the system. If the subscriber already exists, another subscribe event will be sent, triggering any automations that take place upon subscription. Please be aware of the potential consequences.
You may optionally pass any fields that you wish to be set on the subscriber during creation.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: 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'
]
]);
This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.unsubscribe
method.
Unsubscribes an email in the system. If the email is already unsubscribed, another unsubscribe event will be sent, triggering any automations that take place upon an unsubscribe happening. Please be aware of the potential consequences.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: RemoveSubscriberParameters
$bento->V1->removeSubscriber([
'email' => 'test@bentonow.com'
]);
This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.addField
method.
Sets the passed-in custom fields on the subscriber, creating the subscriber if it does not exist. If the fields are already set on the subscriber, the event will be sent, triggering any automations that take place upon fields being updated. Please be aware of the potential consequences.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: UpdateFieldsParameters
$bento->V1->updateFields([
'email' => 'test@bentonow.com',
'fields' => [
'firstName' => 'Test',
]
]);
This TRIGGERS automations! - There is no way to achieve this same behavior without triggering automations.
Tracks a purchase in Bento, used to calculate LTV for your subscribers. The values that are received should be numbers, in cents. For example, $1.00
should be 100
.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: TrackPurchaseParameters
$bento->V1->trackPurchase([
'email' => 'test@bentonow.com',
'purchaseDetails' => [
'unique' => [
'key' => 1234
],
'value' => [
'amount' => 100,
'currency' => 'USD'
]
]
]);
This TRIGGERS automations! - There is no way to achieve this same behavior without triggering automations.
Tracks a custom event in Bento.
Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.
Returns true
if the event was successfully dispatched. Returns false
otherwise.
Reference Types: TrackParameters
$bento->V1->track([
'email' => 'test@bentonow.com',
'type' => '$custom.event',
'details' => [
'fromCustomEvent' => true
]
]);
This does not trigger automations! - If you wish to trigger automations, please batch import events with the type set to BentoEvents.SUBSCRIBE
, or $subscribe
. Note that the batch event import cannot attach custom fields and will ignore everything except the email.
Creates a batch job to import subscribers into the system. You can pass in between 1 and 1,000 subscribers to import. Each subscriber must have an email, and may optionally have any additional fields. The additional fields are added as custom fields on the subscriber.
This method is processed by the Bento import queues and it may take between 1 and 5 minutes for the results to appear in your dashboard.
Returns the number of subscribers that were imported.
Reference Types: BatchImportSubscribersParameter
$bento->V1->Batch->importSubscribers([
'subscribers' => [
['email' => 'test@bentonow.com', 'age' => 21],
['email' => 'test2@bentonow.com'],
['email' => 'test3@bentonow.com', 'name' => 'Test User']
]
]);
Creates a batch job to import events into the system. You can pass in between 1 and 1,000 events to import. Each event must have an email and a type. In addition to this, you my pass in additional data in the details
property,
Returns the number of events that were imported.
Reference Types: 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'
]
]
]);
This does not trigger automations! - If you wish to trigger automations, please use the core module's tagSubscriber
method.
Adds a tag to the subscriber with the matching email.
Note that both the tag and the subscriber will be created if either is missing from system.
Reference Types: AddTagParameters, Subscriber
$bento->V1->Commands->addTag([
'email' => 'test@bentonow.com',
'tagName' => 'Test Tag'
]);
Removes the specified tag from the subscriber with the matching email.
Reference Types: RemoveTagParameters, Subscriber
$bento->V1->Commands->removeTag([
'email' => 'test@bentonow.com',
'tagName' => 'Test Tag'
]);
This does not trigger automations! - If you wish to trigger automations, please use the core module's updateFields
method.
Adds a field to the subscriber with the matching email.
Note that both the field and the subscriber will be created if either is missing from system.
Reference Types: AddFieldParameters, Subscriber
$bento->V1->Commands->addField([
'email' => 'test@bentonow.com',
'field' => [
'key' => 'testKey',
'value' => 'testValue'
]
]);
Removes a field to the subscriber with the matching email.
Reference Types: RemoveFieldParameters, Subscriber
$bento->V1->Commands->removeField([
'email' => 'test@bentonow.com',
'fieldName' => 'testField'
]);
This does not trigger automations! - If you wish to trigger automations, please use the core module's addSubscriber
method.
Subscribes the supplied email to Bento. If the email does not exist, it is created.
If the subscriber had previously unsubscribed, they will be re-subscribed.
Reference Types: SubscribeParameters, Subscriber
$bento->V1->Commands->subscribe([
'email' => 'test@bentonow.com'
]);
This does not trigger automations! - If you wish to trigger automations, please use the core module's removeSubscriber
method.
Unsubscribes the supplied email to Bento. If the email does not exist, it is created and immediately unsubscribed. If they had already unsubscribed, the unsubscribed_at
property is updated.
Reference Types: UnsubscribeParameters, Subscriber
$bento->V1->Commands->unsubscribe([
'email' => 'test@bentonow.com',
]);
EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.
Attempts to validate the email. You can provide additional information to further refine the validation.
If a name is provided, it compares it against the US Census Data, and so the results may be biased.
Reference Types: ValidateEmailParameters
$bento->V1->Experimental->validateEmail([
'email' => 'test@bentonow.com',
]);
EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.
Attempts to guess the gender of the person given a provided name. It compares the name against the US Census Data, and so the results may be biased.
It is possible for the gender to be unknown if the system cannot confidently conclude what gender it may be.
Reference Types: GuessGenderParameters, GuessGenderResponse
$bento->V1->Experimental->guessGender([
'name' => 'Jesse',
]);
EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.
Attempts to provide location data given a provided IP address.
Reference Types: GeolocateParameters, LocationData
$bento->V1->Experimental->geolocate([
'ip' => '127.0.0.1',
]);
EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.
Looks up the provided URL or IP Address against various blacklists to see if the site has been blacklisted anywhere.
Reference Types: BlacklistParameters, BlacklistResponse
$bento->V1->Experimental->checkBlacklist([
'domain' => 'bentonow.com',
]);
Returns all of the fields for the site.
Reference Types: Field
$bento->V1->Fields->getFields();
Creates a field inside of Bento. The name of the field is automatically generated from the key that is passed in upon creation. For example:
Key | Name |
---|---|
'thisIsAKey' |
'This Is A Key' |
'this is a key' |
'This Is A Key' |
'this-is-a-key' |
'This Is A Key' |
'this_is_a_key' |
'This Is A Key' |
Reference Types: CreateFieldParameters, Field
$bento->V1->Fields->createField([
'key' => 'testKey'
]);
Returns all of the responses for the form with the specified identifier.
Reference Types: FormResponse
$bento->V1->Forms->getResponses('test-formid-1234');
Returns the subscriber with the specified email or UUID.
Reference Types: GetSubscribersParameters, Subscriber
$bento->V1->Subscribers->getSubscribers([
'uuid' => '1234'
]);
$bento->V1->Subscribers->getSubscribers([
'email' => 'test@bentonow.com'
]);
Creates a subscriber inside of Bento.
Reference Types: CreateSubscriberParameters, Subscriber
$bento->V1->Subscribers->createSubscriber([
'email' => 'test@bentonow.com'
]);
Returns all of the fields for the site.
Reference Types: Tag
$bento->V1->Tags->getTags();
Creates a tag inside of Bento.
Reference Types: Tag
$bento->V1->Tags->createTag([
'name' => 'test tag'
]);
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
field | mixed |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
fields | mixed |
none | ❌ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
tagName | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
events | BentoEvent[] |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
subscribers | ({ email: string } & mixed)[] |
none | ✔️ |
This type is a discriminated union of a few different types. Each of these types are documented below:
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
details | mixed |
none | ✔️ |
string |
none | ✔️ | |
type | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
details | PurchaseDetails |
none | ✔️ |
string |
none | ✔️ | |
type | BentoEvents.PURCHASE | '$purchase' |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
fields | mixed |
none | ❌ |
type | BentoEvents.SUBSCRIBE | '$subscribe' |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
details | { tag: string } |
none | ✔️ |
string |
none | ✔️ | |
type | BentoEvents.TAG | '$tag' |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
type | BentoEvents.UNSUBSCRIBE | '$unsubscribe' |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
type | BentoEvents.UPDATE_FIELDS | '$update_fields' |
none | ✔️ |
fields | mixed |
none | ✔️ |
Note that this takes either domain
or ip
, but never both.
Property | Type | Default | Required |
---|---|---|---|
domain | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
ip | string |
none | ✔️ |
The results is an object where the key is the name of the blacklist that was checked, and the value is whether or not the domain/IP appeared on that blacklist.
Property | Type | Default | Required |
---|---|---|---|
description | string |
none | ✔️ |
query | string |
none | ✔️ |
results | mixed |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
height | string |
none | ✔️ |
user_agent | string |
none | ✔️ |
width | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
key | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
name | string |
none | ✔️ |
This is an enum with the following values:
Name | Value |
---|---|
EVENTS | 'events' |
TAGS | 'tags' |
VISITORS | 'visitors' |
VISITORS_FIELDS | 'visitors-fields' |
Property | Type | Default | Required |
---|---|---|---|
attributes | FieldAttributes |
none | ✔️ |
id | string |
none | ✔️ |
type | EntityType.VISITORS_FIELDS |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
created_at | string |
none | ✔️ |
key | string |
none | ✔️ |
name | string |
none | ✔️ |
whitelisted | boolean | null |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
attributes | FormResponseAttributes |
none | ✔️ |
id | string |
none | ✔️ |
type | EntityType.EVENTS |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
data | FormResponseData |
none | ✔️ |
uuid | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
browser | BrowserData |
none | ✔️ |
date | string |
none | ✔️ |
details | mixed |
none | ✔️ |
fields | mixed |
none | ✔️ |
id | string |
none | ✔️ |
identity | IdentityData |
none | ✔️ |
ip | string |
none | ✔️ |
location | LocationData |
none | ✔️ |
page | PageData |
none | ✔️ |
site | string |
none | ✔️ |
type | string |
none | ✔️ |
visit | string |
none | ✔️ |
visitor | string |
none | ✔️ |
Note that this takes either email
or uuid
, but never both.
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
uuid | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
ip | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
name | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
confidence | number | null |
none | ✔️ |
gender | string | null |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
city_name | string |
none | ❌ |
continent_code | string |
none | ❌ |
country_code2 | string |
none | ❌ |
country_code3 | string |
none | ❌ |
country_name | string |
none | ❌ |
ip | string |
none | ❌ |
latitude | number |
none | ❌ |
longitude | number |
none | ❌ |
postal_code | string |
none | ❌ |
real_region_name | string |
none | ❌ |
region_name | string |
none | ❌ |
request | string |
none | ❌ |
Property | Type | Default | Required |
---|---|---|---|
host | string |
none | ✔️ |
path | string |
none | ✔️ |
protocol | string |
none | ✔️ |
referrer | string |
none | ✔️ |
url | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
abandoned_checkout_url | string |
none | ❌ |
items | PurchaseItem[] |
none | ❌ |
Property | Type | Default | Required |
---|---|---|---|
unique | { key: string | number; } |
none | ✔️ |
value | { currency: string; amount: number; } |
none | ✔️ |
cart | PurchaseCart |
none | ❌ |
In addition to the properties below, you can pass any other properties that you want as part of the PurchaseItem
.
Property | Type | Default | Required |
---|---|---|---|
product_sku | string |
none | ❌ |
product_name | string |
none | ❌ |
quantity | number |
none | ❌ |
product_price | number |
none | ❌ |
product_id | string |
none | ❌ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
fieldName | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
tagName | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
attributes | SubscriberAttributes |
none | ✔️ |
id | string |
none | ✔️ |
type | EntityType.VISITOR |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
cached_tag_ids | string[] |
none | ✔️ |
string |
none | ✔️ | |
fields | mixed | null |
none | ✔️ |
unsubscribed_at | string |
none | ✔️ |
uuid | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
created_at | string |
none | ✔️ |
discarded_at | string | null |
none | ✔️ |
name | string | null |
none | ✔️ |
site_id | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
attributes | TagAttributes |
none | ✔️ |
id | string |
none | ✔️ |
type | EntityType.TAG |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
tagName | string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
type | string |
none | ✔️ |
details | mixed |
none | ❌ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
purchaseDetails | PurchaseDetails |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
date | Date |
none | ❌ |
string |
none | ✔️ | |
fields | mixed |
none | ✔️ |
Property | Type | Default | Required |
---|---|---|---|
string |
none | ✔️ | |
ip | string |
none | ❌ |
name | string |
none | ❌ |
userAgent | string |
none | ❌ |
- Tracking: All events must be identified. Anonymous support coming soon!
- Tracking: Most events and indexed inside Bento within a few seconds.
- If you need support, just let us know!
Bug reports and pull requests are welcome on GitHub at https://github.com/bentonow/bento-php-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The package is available as open source under the terms of the MIT License.