Tip
Need help? Join our Discord or email jesse@bentonow.com for personalized support.
The Bento Node.js SDK makes it quick and easy to build an excellent analytics experience in your Node.js application. We provide powerful and customizable APIs that can be used out-of-the-box to track your users' behavior and manage subscribers. We also expose low-level APIs so that you can build fully custom experiences.
Get started with our 📚 integration guides, or 📘 browse the SDK reference.
🐶 Battle-tested by NativShark Bento Production (a Bento customer)!
❤️ Thank you @HelloKashif from IPInfo for your contribution.
❤️ Thank you @jonsherrard from Devular for your contribution.
- Simple event tracking: We make it easy for you to track user events and behavior in your application.
- Subscriber management: Easily add, update, and remove subscribers from your Bento account.
- Custom fields: Track and update custom fields for your subscribers to store additional data.
- Purchase tracking: Monitor customer purchases and calculate lifetime value (LTV) for your subscribers.
- Batch operations: Perform bulk imports of subscribers and events for efficient data management.
- TypeScript support: The SDK is written in TypeScript and provides type definitions for a better development experience.
The Bento Node.js SDK requires Node.js version 12 or later.
Bento Account for a valid SITE_UUID, BENTO_PUBLISHABLE_KEY & BENTO_SECRET_KEY.
Install the Bento SDK in your project folder:
# Using npm
npm install @bentonow/bento-node-sdk --save
# Using Bun
bun add @bentonow/bento-node-sdk# Install dependencies
bun install
# Run tests
bun test
# Run tests with coverage
bun test:coverage
# Build the package
bun run build
# Lint code
bun run lint
# Format code
bun run format# Install dependencies
npm install
# Run tests
npm run test:npm
# Run tests with coverage
npm run test:coverage:npm
# Build the package
npm run build:npm
# Lint code
npm run lint
# Format code
npm run formatInitialize the Bento client and start tracking events:
import { Analytics } from '@bentonow/bento-node-sdk';
const bento = new Analytics({
authentication: {
publishableKey: 'bento-publishable-key',
secretKey: 'bento-secret-key',
},
siteUuid: 'bento-site-uuid',
});
bento.V1.track({
email: 'user@example.com',
type: '$formSubmitted',
fields: {
first_name: 'John',
last_name: 'Doe',
},
details: {
fromCustomEvent: true,
},
}).then(result => console.log(result));The Bento SDK provides several modules for different operations:
Core functionality for tracking events and managing subscribers.
Tags a subscriber with a specific tag.
bento.V1.tagSubscriber({
email: 'user@example.com',
tagName: 'New Customer',
}).then(result => console.log(result));Adds a new subscriber to your Bento account.
bento.V1.addSubscriber({
email: 'newuser@example.com',
fields: {
firstName: 'John',
lastName: 'Doe',
},
}).then(result => console.log(result));Removes a subscriber from your Bento account.
bento.V1.removeSubscriber({
email: 'user@example.com',
}).then(result => console.log(result));Updates custom fields for a subscriber.
bento.V1.updateFields({
email: 'user@example.com',
fields: {
lastPurchaseDate: new Date(),
},
}).then(result => console.log(result));Tracks a custom event for a subscriber.
bento.V1.track({
email: 'user@example.com',
type: '$pageView',
details: {
url: '/products',
},
}).then(result => console.log(result));Tracks a purchase event for a subscriber.
bento.V1.trackPurchase({
email: 'user@example.com',
purchaseDetails: {
unique: { key: 'order-123' },
value: { amount: 9999, currency: 'USD' },
},
}).then(result => console.log(result));Perform bulk operations for importing subscribers and events.
Imports multiple subscribers in a single operation.
bento.V1.Batch.importSubscribers({
subscribers: [
{ email: 'user1@example.com', firstName: 'Alice' },
{ email: 'user2@example.com', firstName: 'Bob' },
],
}).then(result => console.log(result));Imports multiple events in a single operation.
bento.V1.Batch.importEvents({
events: [
{ email: 'user@example.com', type: '$login' },
{ email: 'user@example.com', type: '$pageView', details: { url: '/home' } },
],
}).then(result => console.log(result));Execute specific commands for subscriber management.
Adds a tag to a subscriber.
bento.V1.Commands.addTag({
email: 'user@example.com',
tagName: 'VIP',
}).then(result => console.log(result));Removes a tag from a subscriber.
bento.V1.Commands.removeTag({
email: 'user@example.com',
tagName: 'VIP',
}).then(result => console.log(result));Adds a custom field to a subscriber.
bento.V1.Commands.addField({
email: 'user@example.com',
field: {
key: 'favoriteColor',
value: 'blue',
},
}).then(result => console.log(result));Removes a custom field from a subscriber.
bento.V1.Commands.removeField({
email: 'user@example.com',
fieldName: 'favoriteColor',
}).then(result => console.log(result));Access experimental features (use with caution).
Attempts to validate an email address.
bento.V1.Experimental.validateEmail({
email: 'user@example.com',
}).then(result => console.log(result));Attempts to guess the gender based on a given name.
bento.V1.Experimental.guessGender({
name: 'Alex',
}).then(result => console.log(result));Manage custom fields for your subscribers.
Retrieves all custom fields defined in your Bento account.
bento.V1.Fields.getFields().then(fields => console.log(fields));Creates a new custom field in your Bento account.
bento.V1.Fields.createField({
key: 'loyaltyPoints',
}).then(result => console.log(result));Retrieve form responses.
Retrieves responses for a specific form.
bento.V1.Forms.getResponses('form-id-123').then(responses => console.log(responses));Manage individual subscribers.
Retrieves subscriber information.
bento.V1.Subscribers.getSubscribers({
email: 'user@example.com',
}).then(subscriber => console.log(subscriber));Creates a new subscriber in your Bento account.
bento.V1.Subscribers.createSubscriber({
email: 'newuser@example.com',
}).then(result => console.log(result));Create and manage tags for subscriber segmentation.
Retrieves all tags defined in your Bento account.
bento.V1.Tags.getTags().then(tags => console.log(tags));Creates a new tag in your Bento account.
bento.V1.Tags.createTag({
name: 'Premium Customer',
}).then(result => console.log(result));For detailed information on each module, refer to the SDK Documentation.
This section provides a detailed reference for the types used in the Bento Node.js SDK.
AddFieldParameters <S>
Parameters for adding a field to a subscriber.
| Property | Type | Required | Description |
|---|---|---|---|
| string | ✔️ | Subscriber's email address | |
| field | { key: keyof S; value: any } | ✔️ | Field to add |
Parameters for adding a new subscriber.
| Property | Type | Required | Description |
|---|---|---|---|
| date | Date | ❌ | Date of subscription |
| string | ✔️ | Subscriber's email address | |
| fields | Partial <S> |
❌ | Additional fields for the subscriber |
Parameters for adding a tag to a subscriber.
| Property | Type | Required | Description |
|---|---|---|---|
| string | ✔️ | Subscriber's email address | |
| tagName | string | ✔️ | Name of the tag to add |
Parameters for batch importing events.
| Property | Type | Required | Description |
|---|---|---|---|
| events | BentoEvent <S>, <E> |
✔️ | Array of events to import |
Parameters for batch importing subscribers.
| Property | Type | Required | Description |
|---|---|---|---|
| subscribers | ({ email: string } & Partial <S>)[] |
✔️ | Array of subscribers to import |
Represents different types of events in Bento. It's a union of the following event types:
- BaseEvent
<E> - PurchaseEvent
- SubscribeEvent
<S> - TagEvent
- UnsubscribeEvent
- UpdateFieldsEvent
<S>
Details of a purchase event.
| Property | Type | Required | Description |
|---|---|---|---|
| unique | { key: string | number } | ✔️ | Unique identifier for the purchase |
| value | { currency: string; amount: number } | ✔️ | Value of the purchase |
| cart | PurchaseCart | ❌ | Additional cart details |
Parameters for changing a subscriber's email.
| Property | Type | Required | Description |
|---|---|---|---|
| oldEmail | string | ✔️ | Current email address |
| newEmail | string | ✔️ | New email address |
Parameters for creating a new field.
| Property | Type | Required | Description |
|---|---|---|---|
| key | string | ✔️ | Key of the new field |
Parameters for creating a new tag.
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✔️ | Name of the new tag |
Represents a subscriber in Bento.
| Property | Type | Required | Description |
|---|---|---|---|
| attributes | SubscriberAttributes <S> |
✔️ | Attributes of the subscriber |
| id | string | ✔️ | Unique identifier |
| type | EntityType.VISITOR | ✔️ | Type of the entity |
Parameters for tracking an event.
| Property | Type | Required | Description |
|---|---|---|---|
| string | ✔️ | Subscriber's email address | |
| type | string | ✔️ | Type of the event |
| details | { [key: string]: any } | ❌ | Additional details of the event |
| fields | Partial <S> |
❌ | Fields to update for the subscriber |
Parameters for validating an email address.
| Property | Type | Required | Description |
|---|---|---|---|
| string | ✔️ | Email address to validate | |
| ip | string | ❌ | IP address of the user |
| name | string | ❌ | Name associated with the email |
| userAgent | string | ❌ | User agent string |
Note: The S and E generic types are used for TypeScript support. S represents the type of your subscriber's custom fields, and E represents the prefix used for custom events. For more details, refer to the TypeScript section of the documentation.
- All events must be identified with an email address.
- Most events are indexed within seconds in your Bento account.
- The SDK supports TypeScript with generics for custom fields and events.
- Batch operations are available for importing subscribers and events efficiently.
- The SDK doesn't currently support anonymous events (coming soon).
We welcome contributions! Please see our contributing guidelines for details on how to submit pull requests, report issues, and suggest improvements.
The Bento SDK for Node.js is available as open source under the terms of the MIT License.