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


export const exampleFile = 'nextjs-guide-examples'
# Bento Next.js Guide

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


<div className="grid grid-cols-1 sm:grid-cols-2 gap-x-4 gap-y-2">
  <GuideLinkCards
    icon={UpBubbleIcon}
    title="Getting Started"
    links={[
      { label: 'Installation', href: '#installation' },
      { label: 'Basic Setup', href: '#basic-setup' },
    ]}
  />

  <GuideLinkCards
    icon={ThumbUpIcon}
    title="Beginner Guide"
    links={[
      { label: 'Page View Tracking', href: '#page-view-tracking' },
      { label: 'User Identification', href: '#user-identification' },
      { label: 'Event Tracking', href: '#event-tracking' },
    ]}
  />

  <GuideLinkCards
    icon={EmailBubbleIcon}
    title="Intermediate Guide"
    links={[
      { label: 'Server-Side Integration', href: '#server-side-integration' },
      { label: 'Advanced Configuration', href: '#advanced-configuration' },
      { label: 'TypeScript Support', href: '#typescript-support' },
    ]}
  />

  <GuideLinkCards
    icon={BentoCoinIcon}
    title="Advanced Guide"
    links={[
      { label: 'Custom Events', href: '#custom-events' },
      { label: 'Best Practices', href: '#best-practices' },
    ]}
  />
</div>

### Reference
<div className={'flex flex-col gap-y-1 mb-8'}>
  <div><span className={'text-xl text-violet-500'}>#</span> [API Reference](#api-reference)</div>
  <div><span className={'text-xl text-violet-500'}>#</span> [Troubleshooting](#troubleshooting)</div>
  <div><span className={'text-xl text-violet-500'}>#</span> [FAQ](#faq)</div>
</div>


## Getting Started


<div className={'ml-4'}>
  
    
**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):**

      


</div>


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