Package Exports

@admesh/react-sdk
@admesh/react-sdk/dist/index.esm.js
@admesh/react-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@admesh/react-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: support@admesh.com

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