import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/docs/ui/accordion"


export const exampleFile = 'nextjs-guide-examples'
# 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

  # [API Reference](#api-reference)
  # [Troubleshooting](#troubleshooting)
  # [FAQ](#faq)


## 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](https://app.bentonow.com/account/teams). 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):**

      


## 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 (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


## Advanced Guide


## Custom Events

### E-commerce Events


### User Lifecycle Events


## Best Practices

### Performance Optimization

1. **Lazy Load Analytics**: Only load Bento when needed
2. **Batch Events**: Group related events when possible
3. **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**    | Import types from `@bentonow/bento-nextjs-sdk/types`               |
| **Hydration mismatches** | Use `dynamic` imports with `ssr: false` for client-only components |

#### Debugging


## FAQ


  
    Can I use this with App Router and Pages Router simultaneously?
    
      No, choose the appropriate component for your routing system. Use `BentoAnalytics` for App Router (Next.js 13+) and `BentoLegacyAnalytics` for Pages Router (Next.js 12).
    
  

  
    How do I handle user logout?
    
      When users log out, pass an empty string to the `userEmail` prop or call `window.bento.identify('')` to clear the user identification.
    
  

  
    Is the SDK compatible with React Strict Mode?
    
      Yes, the SDK is designed to work with React Strict Mode. Event handlers are properly debounced to prevent duplicate tracking during development.
    
  

  
    Can I customize the script loading strategy?
    
      Yes, you can use the underlying Next.js `Script` component with different strategies. The default `afterInteractive` works for most cases, but you can use `lazyOnload` for better performance or `beforeInteractive` for critical tracking.
    
  

  
    How do I track events from server components?
    
      Server components can't directly call client-side tracking methods. Instead, use server actions with the Node SDK or pass data to client components that handle the tracking.