Skip to Content
Integrations & SDKsNext.js

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.

Last updated on