Bento NextJs Guide

This guide will help you implement Bento into your NextJs applications, regardless of your development experience.

Getting Started

Beginner Guide

# Page View Tracking

# User Identification

# Event Tracking

Intermediate Guide

# Server-Side Integration

# Advanced Configuration

# TypeScript Support

Advanced Guide

# Custom Events

# Best Practices

Reference

# API Reference

# Troubleshooting

Getting Started

1

Package Installation

Installation

Install the Bento Next.js SDK in your project:

For server-side integration capabilities, also install:

2

Environment Configuration

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.

3

Client Setup

Configure the analytics component in your app layout:

For Next.js 13+ (App Router):

For Next.js 12 (Pages Router):

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 (12): Uses router.events to listen for navigation

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

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

Client-Side Methods

Method	Description	Example
`window.bento.view()`	Track page view	`window.bento.view()`
`window.bento.identify(email)`	Identify user	`window.bento.identify('[email protected]')`
`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	Import types from `@bentonow/bento-nextjs-sdk/types`
Hydration mismatches	Use `dynamic` imports with `ssr: false` for client-only components

Debugging