AdMesh React SDK

Zero-code React SDK for AdMesh recommendations with automatic tracking, viewability detection, and MRC compliance.

Features

• ✅ Zero-Code Integration - Drop-in React components
• ✅ Automatic Tracking - Exposure, click, and conversion tracking
• ✅ MRC Compliance - Viewability detection using Intersection Observer
• ✅ Multiple Layouts - Product card, ecommerce, and citation layouts
• ✅ Dark Mode - Automatic dark mode support
• ✅ Responsive - Mobile-friendly design
• ✅ TypeScript - Full TypeScript support
• ✅ Tree-Shakeable - Optimized bundle size

Installation

npm install @admesh/react-sdk
# or
yarn add @admesh/react-sdk
# or
pnpm add @admesh/react-sdk

Quick Start

1. Wrap Your App with Provider

import { AdMeshProvider } from '@admesh/react-sdk';

function App() {
  return (
    <AdMeshProvider
      config={{
        apiKey: 'admesh_prod_your_api_key',
        apiBaseUrl: 'https://api.admesh.com',
        debug: true
      }}
    >
      <YourApp />
    </AdMeshProvider>
  );
}

2. Use the Hook to Fetch Recommendations

import { useRecommendations, RecommendationGrid } from '@admesh/react-sdk';

function RecommendationsPage() {
  const { recommendations, loading, error } = useRecommendations({
    query: 'laptop under $1000',
    limit: 5
  });

  return (
    <RecommendationGrid
      recommendations={recommendations}
      loading={loading}
      error={error}
    />
  );
}

Usage Examples

Basic Grid

import { useRecommendations, RecommendationGrid } from '@admesh/react-sdk';

export function BasicExample() {
  const { recommendations, loading, error } = useRecommendations({
    query: 'best laptops',
    limit: 6
  });

  return (
    <RecommendationGrid
      recommendations={recommendations}
      loading={loading}
      error={error}
      columns={3}
    />
  );
}

With Callbacks

export function AdvancedExample() {
  const { recommendations, loading, error } = useRecommendations({
    query: 'best laptops'
  });

  return (
    <RecommendationGrid
      recommendations={recommendations}
      loading={loading}
      error={error}
      onRecommendationVisible={(rec, metrics) => {
        console.log(`${rec.title} is visible:`, metrics);
      }}
      onRecommendationClick={(rec) => {
        console.log(`Clicked: ${rec.title}`);
      }}
    />
  );
}

Custom Viewability Tracking

import { useViewabilityTracker } from '@admesh/react-sdk';

export function CustomTracking() {
  const { ref, isVisible, metrics } = useViewabilityTracker({
    threshold: 75,
    duration: 2000,
    onVisible: (metrics) => {
      console.log('Element is visible:', metrics);
    }
  });

  return (
    <div ref={ref}>
      {isVisible && <p>This element is visible!</p>}
      {metrics && <p>Viewability: {metrics.score}%</p>}
    </div>
  );
}

API Reference

AdMeshProvider

Wraps your app and provides AdMesh context.

<AdMeshProvider
  config={{
    apiKey: string;              // Required: Your API key
    apiBaseUrl?: string;         // Optional: API base URL
    viewabilityConfig?: {        // Optional: Viewability settings
      threshold: number;         // 0-100, default: 50
      duration: number;          // milliseconds, default: 1000
    };
    debug?: boolean;             // Optional: Enable debug logging
  }}
>
  {children}
</AdMeshProvider>

useRecommendations

Hook to fetch recommendations.

const { recommendations, loading, error, refetch } = useRecommendations({
  query: string;           // Required: Search query
  limit?: number;          // Optional: Max results (default: 5)
  category?: string;       // Optional: Product category
  maxPrice?: number;       // Optional: Max price in cents
  minRating?: number;      // Optional: Min rating (0-5)
  enabled?: boolean;       // Optional: Enable/disable fetching
});

useViewabilityTracker

Hook for MRC-compliant viewability tracking.

const { ref, isVisible, metrics } = useViewabilityTracker({
  threshold?: number;      // 0-100, default from config
  duration?: number;       // milliseconds, default from config
  onVisible?: (metrics) => void;  // Callback when visible
});

RecommendationCard

Component for a single recommendation.

<RecommendationCard
  recommendation={rec}
  onVisible={(metrics) => {}}
  onClick={() => {}}
  className="custom-class"
/>

RecommendationGrid

Component for a grid of recommendations.

<RecommendationGrid
  recommendations={recs}
  loading={false}
  error={null}
  onRecommendationVisible={(rec, metrics) => {}}
  onRecommendationClick={(rec) => {}}
  columns={3}
  gap="16px"
  className="custom-class"
/>

Styling

The SDK includes default styles. Customize with CSS:

.admesh-recommendation-card {
  border-radius: 8px;
}

.admesh-cta-button {
  background: #007bff;
}

Browser Support

• Chrome 51+
• Firefox 55+
• Safari 12.1+
• Edge 15+
• Mobile browsers (iOS Safari 12.2+, Chrome Mobile)

Performance

• Bundle size: ~15 KB (minified + gzipped)
• SDK initialization: <100ms
• Recommendation fetch: 200-500ms
• Display rendering: <50ms

Troubleshooting

SDK Not Loading

// Check if provider is wrapping your component
<AdMeshProvider config={...}>
  <YourComponent />
</AdMeshProvider>

No Recommendations

// Enable debug mode
<AdMeshProvider
  config={{
    apiKey: 'admesh_prod_xxx',
    debug: true  // Check console for errors
  }}
>

Tracking Not Working

• Verify API key is valid
• Check network tab for API calls
• Ensure recommendations are visible
• Check rate limits

Support

• Documentation: https://docs.admesh.com
• Issues: https://github.com/admesh/react-sdk/issues
• Email: [email protected]

License

MIT

Contributing

Contributions welcome! Please read our contributing guidelines.

Changelog

1.0.0

• Initial release
• React 16.8+ support
• TypeScript support
• MRC viewability tracking
• Automatic exposure/click tracking