React Hooks API Reference

Complete reference for all React hooks provided by the Adopture Next.js SDK.

useTrack

The primary hook for tracking feature usage events.

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

const { track, isReady } = useTrack();

Returns

Property	Type	Description
`track`	`(featureId: string, metadata?: Record<string, unknown>) => Promise<void>`	Track feature usage
`isReady`	`boolean`	Whether tracking is ready

Example

'use client';

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

export function FeatureButton() {
  const { track, isReady } = useTrack();

  const handleClick = async () => {
    if (isReady) {
      await track('feature-button-clicked', {
        location: 'sidebar',
        timestamp: new Date().toISOString(),
      });
    }
  };

  return <button onClick={handleClick}>Use Feature</button>;
}

useExpose

Hook for tracking feature exposure events.

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

const { expose, isReady } = useExpose();

Returns

Property	Type	Description
`expose`	`(featureId: string, exposureChannel?: string, metadata?: Record<string, unknown>, options?: VisibilityTrackingOptions) => Promise<void>`	Track feature exposure
`isReady`	`boolean`	Whether tracking is ready

Parameters

featureId (string): Unique identifier for the feature
exposureChannel (string, optional): Channel where exposure occurred (e.g., 'homepage', 'navigation')
metadata (Record<string, unknown>, optional): Additional context data
options (VisibilityTrackingOptions, optional): Visibility tracking configuration

Example

'use client';

import { useExpose } from '@adopture/next';
import { useEffect } from 'react';

export function FeatureBanner() {
  const { expose, isReady } = useExpose();

  useEffect(() => {
    if (isReady) {
      expose('feature-banner', 'homepage', {
        position: 'top',
        campaign: 'feature-launch',
      });
    }
  }, [expose, isReady]);

  return <div>New Feature Available!</div>;
}

useIdentify

Hook for identifying users and setting user properties.

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

const { identify, isReady } = useIdentify();

Returns

Property	Type	Description
`identify`	`(userId: string, properties?: UserProperties) => Promise<void>`	Identify user
`isReady`	`boolean`	Whether identification is ready

UserProperties Type

interface UserProperties {
  email?: string;
  name?: string;
  plan?: string;
  company?: string;
  role?: string;
  signupDate?: string;
  [key: string]: any;
}

Example

'use client';

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

export function LoginComponent() {
  const { identify, isReady } = useIdentify();

  const handleLogin = async (userId: string) => {
    if (isReady) {
      await identify(userId, {
        email: 'user@example.com',
        name: 'John Doe',
        plan: 'premium',
        company: 'Acme Corp',
        role: 'admin',
      });
    }
  };

  return <button onClick={() => handleLogin('user-123')}>Login</button>;
}

useAdoptureTracking

Main hook that combines all tracking functionality.

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

const {
  track,
  expose,
  identify,
  tracker,
  isInitialized,
  isLoading,
  error
} = useAdoptureTracking();

Returns

Property	Type	Description
`track`	`(featureId: string, metadata?: Record<string, unknown>) => Promise<void>`	Track feature usage
`expose`	`(featureId: string, exposureChannel?: string, metadata?: Record<string, unknown>, options?: VisibilityTrackingOptions) => Promise<void>`	Track feature exposure
`identify`	`(userId: string, properties?: UserProperties) => Promise<void>`	Identify user
`tracker`	`NextAdoptureTracker \| null`	Direct access to tracker instance
`isInitialized`	`boolean`	Whether SDK is initialized
`isLoading`	`boolean`	Whether SDK is still loading
`error`	`Error \| null`	Any initialization error

Example

'use client';

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

export function AdvancedComponent() {
  const {
    track,
    expose,
    identify,
    isInitialized,
    isLoading,
    error
  } = useAdoptureTracking();

  if (isLoading) return <div>Loading tracking...</div>;
  if (error) return <div>Tracking error: {error.message}</div>;

  const handleComplexAction = async () => {
    if (!isInitialized) return;

    await track('complex-action-started');
    await expose('related-feature', 'action-flow');
  };

  return <button onClick={handleComplexAction}>Complex Action</button>;
}

useComponentTracking

Hook for automatic component visibility tracking.

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

useComponentTracking(featureId: string, options?: ComponentTrackingOptions);

Parameters

featureId (string): Unique identifier for the component/feature
options (ComponentTrackingOptions, optional): Tracking configuration

ComponentTrackingOptions Type

interface ComponentTrackingOptions {
  exposureChannel?: string;
  metadata?: Record<string, unknown>;
  trackOnMount?: boolean;
  trackVisibility?: boolean;
  visibilityThreshold?: number;
}

Example

'use client';

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

export function ProductCard({ productId }: { productId: string }) {
  // Automatically track when component becomes visible
  useComponentTracking('product-card-view', {
    exposureChannel: 'product-listing',
    metadata: {
      productId,
      section: 'featured',
    },
    trackVisibility: true,
    visibilityThreshold: 0.5, // 50% visible
  });

  return <div>Product {productId}</div>;
}

useInteractionTracking

Hook for tracking user interactions within a component.

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

const { trackInteraction } = useInteractionTracking(baseFeatureId: string);

Returns

Property	Type	Description
`trackInteraction`	`(action: string, metadata?: Record<string, unknown>) => Promise<void>`	Track interaction

Example

'use client';

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

export function InteractiveWidget() {
  const { trackInteraction } = useInteractionTracking('analytics-widget');

  const handleExpand = () => {
    trackInteraction('expand', { from: 'collapsed' });
  };

  const handleFilter = (filterType: string) => {
    trackInteraction('filter-applied', { filterType });
  };

  return (
    <div>
      <button onClick={handleExpand}>Expand</button>
      <button onClick={() => handleFilter('date')}>Filter by Date</button>
    </div>
  );
}

useVisibilityTracking

Hook for advanced visibility tracking with custom options.

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

const { trackVisibility } = useVisibilityTracking();

Returns

Property	Type	Description
`trackVisibility`	`(featureId: string, element: HTMLElement, options?: VisibilityTrackingOptions) => void`	Track element visibility

VisibilityTrackingOptions Type

interface VisibilityTrackingOptions {
  threshold?: number; // 0-1, percentage visible
  delay?: number; // ms to wait before tracking
  once?: boolean; // track only once
  metadata?: Record<string, unknown>;
}

Example

'use client';

import { useVisibilityTracking } from '@adopture/next';
import { useRef, useEffect } from 'react';

export function VisibilityExample() {
  const { trackVisibility } = useVisibilityTracking();
  const elementRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (elementRef.current) {
      trackVisibility('important-content', elementRef.current, {
        threshold: 0.8, // 80% visible
        delay: 1000, // wait 1 second
        once: true, // track only once
        metadata: { section: 'hero' },
      });
    }
  }, [trackVisibility]);

  return <div ref={elementRef}>Important content</div>;
}

usePerformanceTracking

Hook for tracking performance metrics.

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

const { trackPerformance } = usePerformanceTracking();

Returns

Property	Type	Description
`trackPerformance`	`(eventName: string, metrics: PerformanceMetrics) => Promise<void>`	Track performance

PerformanceMetrics Type

interface PerformanceMetrics {
  duration?: number;
  startTime?: number;
  endTime?: number;
  size?: number;
  metadata?: Record<string, unknown>;
}

Example

'use client';

import { usePerformanceTracking } from '@adopture/next';
import { useEffect } from 'react';

export function PerformanceExample() {
  const { trackPerformance } = usePerformanceTracking();

  useEffect(() => {
    const startTime = performance.now();

    // Simulate data loading
    loadData().then(() => {
      const endTime = performance.now();
      trackPerformance('data-load-complete', {
        duration: endTime - startTime,
        startTime,
        endTime,
        metadata: { dataType: 'user-analytics' },
      });
    });
  }, [trackPerformance]);

  return <div>Loading data...</div>;
}

Common Patterns

Error Handling

const { track } = useTrack();

const handleAction = async () => {
  try {
    await track('action-attempted');
    // Perform action
    await track('action-completed');
  } catch (error) {
    console.error('Tracking failed:', error);
    // Continue with the action regardless
  }
};

Conditional Tracking

const { track } = useTrack();

const handlePremiumFeature = () => {
  if (user.plan === 'premium') {
    track('premium-feature-accessed', {
      feature: 'advanced-analytics',
      plan: user.plan,
    });
  }
};

Batching Events

const { track } = useTrack();

const handleMultiStepAction = async () => {
  // Events are automatically batched by the SDK
  await track('step-1-completed');
  await track('step-2-completed');
  await track('step-3-completed');
  // All events sent together when batch is full or flushed
};

Best Practices

Always use 'use client': All hooks require client-side rendering
Check isReady: Verify hooks are ready before tracking
Handle errors gracefully: Don't let tracking failures break your app
Use meaningful feature IDs: Make them descriptive and consistent
Include relevant metadata: Add context that makes analytics actionable
Respect user privacy: Don't track sensitive information

TypeScript Support

All hooks are fully typed with TypeScript. Import types as needed:

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

React Hooks

On this page