API Reference

Complete technical reference for the Adopture Next.js SDK.

Overview

The Adopture Next.js SDK provides a comprehensive set of React hooks and provider components for feature adoption tracking.

Components

Provider Components

View Provider Components Documentation →

Essential wrapper components for your application:

AdoptureProvider - App Router provider
AdopturePagesProvider - Pages Router provider
AdoptureBootstrap - Server-side data injection

import { AdoptureProvider } from '@adopture/next';

<AdoptureProvider config={config}>
  {children}
</AdoptureProvider>

Hooks

React Hooks

View React Hooks Documentation →

Powerful hooks for tracking user interactions:

useTrack() - Track feature usage events
useExpose() - Track feature exposure
useIdentify() - Identify users
useAdoptureTracking() - Combined functionality
useComponentTracking() - Automatic visibility tracking

import { useTrack, useExpose, useIdentify } from '@adopture/next';

const { track } = useTrack();
const { expose } = useExpose();
const { identify } = useIdentify();

TypeScript Support

The SDK is built with TypeScript and provides complete type definitions:

import type {
  NextAdoptureConfig,
  UserProperties,
  VisibilityTrackingOptions,
  ComponentTrackingOptions,
  PerformanceMetrics,
} from '@adopture/next';

Quick Reference

Essential Imports

// Provider components
import {
  AdoptureProvider,
  AdopturePagesProvider
} from '@adopture/next';

// Tracking hooks
import {
  useTrack,
  useExpose,
  useIdentify,
  useAdoptureTracking
} from '@adopture/next';

// Specialized hooks
import {
  useComponentTracking,
  useInteractionTracking,
  useVisibilityTracking,
  usePerformanceTracking
} from '@adopture/next';

Common Patterns

Basic Event Tracking

const { track } = useTrack();
await track('feature-used', { source: 'button' });

Feature Exposure

const { expose } = useExpose();
await expose('feature-banner', 'homepage');

User Identification

const { identify } = useIdentify();
await identify('user-123', { plan: 'premium' });

Component Visibility

useComponentTracking('product-card', {
  exposureChannel: 'product-listing',
  metadata: { productId: '123' }
});

Configuration

Environment Variables

NEXT_PUBLIC_ADOPTURE_API_KEY=your_api_key_here
NEXT_PUBLIC_ADOPTURE_DEBUG=true
NEXT_PUBLIC_ADOPTURE_BATCH_SIZE=50
NEXT_PUBLIC_ADOPTURE_FLUSH_INTERVAL=5000

Provider Configuration

const config = {
  debug: process.env.NODE_ENV === 'development',
  batchSize: 100,
  flushInterval: 3000,
  timeout: 10000,
};

<AdoptureProvider config={config}>
  {children}
</AdoptureProvider>

Error Handling

Provider Level

<AdoptureProvider
  fallback={<div>Analytics unavailable</div>}
  loadingComponent={<div>Loading...</div>}
>
  {children}
</AdoptureProvider>

Hook Level

const { track, isReady } = useTrack();

const handleAction = async () => {
  try {
    if (isReady) {
      await track('action-performed');
    }
  } catch (error) {
    console.error('Tracking failed:', error);
  }
};

Best Practices

Always use 'use client' for components with hooks
Check isReady before tracking critical events
Handle errors gracefully to avoid breaking user experience
Use meaningful event names for better analytics
Include relevant metadata for actionable insights

Migration Guide

From Other Analytics

// Before (other analytics)
analytics.track('event-name', properties);

// After (Adopture)
const { track } = useTrack();
await track('event-name', properties);

Gradual Adoption

You can gradually migrate by running both systems:

const { track: adoptureTrack } = useTrack();

const trackEvent = async (event, properties) => {
  // Old system
  analytics.track(event, properties);

  // New system
  await adoptureTrack(event, properties);
};

Support

Documentation: Complete guides
Examples: Practical examples
Community: Discord support channel
Email: help@adopture.com

API Reference

On this page