Bento Next.js Guide
This guide covers adding Bento to your Next.js application: client-side tracking, server-side integration, and TypeScript support for both App Router and Pages Router.
Reference
Getting Started
Installation
The SDK supports Next.js 12 or later. The App Router component needs Next.js 13 or later. It requires Node.js 18.17 or later.
Install the Bento Next.js SDK in your project:
For server-side integration capabilities, also install:
Basic Setup
Add your Bento credentials to your environment variables:
You can find your keys in your Bento Team Settings. Click
Your Private API Keys and generate a key set if needed.
Configure the analytics component in your app layout:
For Next.js 13+ (App Router):
For the Pages Router (Next.js 12 or later):
Beginner Guide
Page View Tracking
Page views are automatically tracked when you include the Bento analytics components. The SDK handles route changes and sends view events to Bento.
How It Works
The SDK uses Next.js routing hooks to detect navigation:
- App Router (13+): Uses
usePathname()to detect route changes - Pages Router: Uses
router.eventsto listen forrouteChangeComplete. The script records the first page view when it loads.
Manual Implementation
If you need more control over page view tracking:
App Router:
Pages Router:
User Identification
Identify users to connect their actions across sessions and devices:
Dynamic User Identification
Manual Identification
Event Tracking
Track custom events to understand user behavior and trigger workflows:
Basic Event Tracking
React Hook for Event Tracking
Intermediate Guide
Server-Side Integration
For server-side event tracking and subscriber management, use the Node SDK:
Server-Side Configuration
API Route Examples
Advanced Configuration
Custom Script Loading
For more control over when and how the Bento script loads:
Conditional Loading
Load Bento only in production or for specific user segments:
TypeScript Support
The SDK includes full TypeScript support with proper type definitions:
Type Definitions
Typed Event Tracking
Advanced Guide
Custom Events
E-commerce Events
User Lifecycle Events
Best Practices
Performance Optimization
- Lazy Load Analytics: Only load Bento when needed
- Batch Events: Group related events when possible
- Debounce Tracking: Prevent spam from rapid user actions
Error Handling
API Reference
Client-Side Methods
| Method | Description | Example |
|---|---|---|
window.bento.view() | Track page view | window.bento.view() |
window.bento.identify(email) | Identify user | window.bento.identify('user@example.com') |
window.bento.track(event, data) | Track custom event | window.bento.track('signup', { plan: 'pro' }) |
window.bento.tag(tag) | Add tag to user | window.bento.tag('premium_user') |
Components
| Component | Props | Description |
|---|---|---|
BentoAnalytics | siteUuid: string, userEmail?: string | App Router analytics |
BentoLegacyAnalytics | siteUuid: string, userEmail?: string | Pages Router analytics |
Hooks
| Hook | Parameters | Returns | Description |
|---|---|---|---|
useBentoAnalytics | userEmail?: string | void | App Router page tracking |
useBentoLegacyAnalytics | userEmail?: string | void | Pages Router page tracking |
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Script not loading | Check NEXT_PUBLIC_BENTO_SITE_ID is set and accessible in browser |
| Events not tracking | Ensure window.bento exists before calling methods |
| TypeScript errors | Declare window.bento in a .d.ts file, as shown in Type Definitions |
| Hydration mismatches | Use dynamic imports with ssr: false for client-only components |