Next.js Integration

Usermaven provides a dedicated SDK for Next.js applications that supports tracking. Our SDK offers:

Automatic page view tracking
Cross-domain tracking support
Flexible event tracking with custom payloads
URL randomization to avoid PII collection
Namespace support for multiple tracking instances

Installation

Install the Usermaven Next.js package:


npm install @usermaven/nextjs
# or
yarn add @usermaven/nextjs

Setup

Provider Setup

Create a layout wrapper component to initialize Usermaven and provide the client to your application. This is typically done in your root layout file (app/layout.tsx):


'use client';
 
import { createClient, UsermavenProvider, usePageView } from "@usermaven/nextjs";
 
// Initialize Usermaven client
const usermavenClient = createClient({
    // Required Configuration
    key: 'your-api-key',
    trackingHost: 'https://events.usermaven.com',
    
    // Optional Configuration
    autocapture: true,             // Enable automatic event capturing
    autoPageview: true,            // Automatically track page views
    randomizeUrl: false,           // Randomize URLs to avoid PII collection
    
    // Cross-domain Tracking (Optional)
    crossDomainLinking: false,     // Enable cross-domain tracking
    domains: 'example.com,example.org',  // Specify allowed domains
    
    // Advanced Configuration (Optional)
    namespace: 'my-app'            // Custom namespace for multiple tracking instances
});
 
// Layout wrapper component
const LayoutWrapper = ({ children }: { children: React.ReactNode }) => {
    // Initialize page view tracking
    usePageView(usermavenClient);
 
    return (
        <UsermavenProvider client={usermavenClient}>
            {children}
        </UsermavenProvider>
    );
}
 
export default LayoutWrapper;

Usage in Components

Tracking Custom Events

Use the useUsermaven hook to track custom events in your components:


'use client';
 
import { useUsermaven } from "@usermaven/nextjs";
 
export default function MyComponent() {
    const { track } = useUsermaven();
 
    const handleButtonClick = () => {
        track('button_click', {
            buttonId: 'submit-button',
            page: 'checkout',
            value: 99.99
        });
    };
 
    return (
        <button onClick={handleButtonClick}>
            Click Me
        </button>
    );
}

Identifying Users

Identify users and set their properties:


'use client';
 
import { useUsermaven } from "@usermaven/nextjs";
 
export default function ProfileComponent() {
    const { id } = useUsermaven();
 
    const identifyUser = () => {
        id({
            // Required attributes
            id: 'lzL24K3kYw',    // Unique ID for the user in database
            email: 'user@domain.com', // Email address for the user
            created_at: '2021-01-20T09:55:35',   // DateTime string when user first signed up
 
            // Recommended attributes
            first_name: 'John',
            last_name: 'Smith',
 
            // Optional attributes
            custom: {
                plan_name: 'premium',
            },
 
            // Company attributes (for multi-user products)
            company: {
                // Required Attributes
                id: 'uPq9oUGrIt', // Company ID in your database
                name: 'Usermaven', // Company Name in your database
                created_at: '2021-01-20T09:55:35',   // DateTime string when company first signed up
 
                // Optional attributes
                custom: {
                    plan: 'enterprise',
                    industry: 'Technology',
                    website: 'https://usermaven.com',
                    employees: 20
                }
            }
        });
    };
 
    return (
        // Your component JSX
    );
}

Configuration Options

Here’s a detailed explanation of all available configuration options:

Required:

key: Your Usermaven API key
trackingHost: The URL of your tracking server

Optional:

autocapture: Enable automatic event capturing (default: false)
autoPageview: Automatically track page views (default: false)
randomizeUrl: Randomize URLs to avoid PII collection (default: false)
namespace: Custom namespace for multiple tracking instances
crossDomainLinking: Enable cross-domain tracking (default: false)
domains: Specify allowed domains for cross-domain tracking (e.g., ‘example.com,example.org’)

For a complete list of configuration options, refer to the Reference Guide .

Example App

For a complete working example, check out our Next.js Example App .