prebid-react/README.md

React-focused Prebid.js integration package

# prebid-react

A React-focused integration package for Prebid.js that makes it easy to implement header bidding in React applications.

## Resources & Further Reading

- 📚 [Understanding Prebid Header Bidding](https://diogoarrais.com/blog/understanding-prebid-header-bidding) - A comprehensive guide to understanding how Prebid.js and header bidding work
- 🌐 [Author's Blog](https://diogoarrais.com/) - More articles and resources about ad tech and web development

## Features

## Installation

```bash
npm install prebid-react
# or
yarn add prebid-react
```

## Quick Start

### 1. Add Google Ad Manager Script

First, add the Google Ad Manager script to your HTML file (typically in `public/index.html`):

```html
<script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
```

### 2. Wrap Your App with PrebidProvider

```tsx
import { PrebidProvider } from 'prebid-react';

const prebidConfig = {
  bidders: [
    {
      bidder: 'rubicon',
      params: {
        accountId: '123456',
        siteId: '789',
        zoneId: '456789'
      }
    },
    {
      bidder: 'appnexus',
      params: {
        placementId: '13144370'
      }
    }
  ],
  timeout: 1000
};

function App() {
  return (
    <PrebidProvider config={prebidConfig}>
      {/* Your app content */}
    </PrebidProvider>
  );
}
```

### 3. Place Ad Units

```tsx
import { AdUnit } from 'prebid-react';

function HomePage() {
  return (
    <div>
      <h1>Welcome to my site</h1>
      
      {/* Leaderboard Ad */}
      <AdUnit
        code="div-leaderboard"
        sizes={[[728, 90], [970, 250]]}
        bids={[
          {
            bidder: 'rubicon',
            params: {
              accountId: '123456',
              siteId: '789',
              zoneId: '456789'
            }
          }
        ]}
      />
      
      {/* Sidebar Ad */}
      <AdUnit
        code="div-sidebar"
        sizes={[[300, 250]]}
        bids={[
          {
            bidder: 'appnexus',
            params: {
              placementId: '13144370'
            }
          }
        ]}
      />
    </div>
  );
}
```

## Advanced Usage

### Manual Refresh

You can use the `usePrebid` hook to manually refresh ad units:

```tsx
import { usePrebid } from 'prebid-react';

function RefreshButton() {
  const { refresh } = usePrebid();

  return (
    <button onClick={refresh}>
      Refresh All Ads
    </button>
  );
}
```

### Custom Ad Unit Configuration

```tsx
import { AdUnit } from 'prebid-react';

function CustomAd() {
  return (
    <AdUnit
      code="div-custom"
      sizes={[[300, 250], [300, 600]]}
      bids={[
        {
          bidder: 'rubicon',
          params: {
            accountId: '123456',
            siteId: '789',
            zoneId: '456789'
          }
        },
        {
          bidder: 'appnexus',
          params: {
            placementId: '13144370'
          }
        }
      ]}
    />
  );
}
```

## API Reference

### PrebidProvider

The main provider component that initializes Prebid.js and provides context to child components.

#### Props

| Prop | Type | Description |
|------|------|-------------|
| config | object | Configuration object for Prebid.js |
| config.bidders | array | Array of bidder configurations |
| config.timeout | number | Timeout for bid requests (in milliseconds) |

### AdUnit

Component for rendering individual ad units.

#### Props

| Prop | Type | Description |
|------|------|-------------|
| code | string | Unique identifier for the ad unit |
| sizes | number[][] | Array of ad sizes (e.g., [[300, 250], [728, 90]]) |
| bids | array | Array of bid configurations for this ad unit |

### usePrebid Hook

A hook for accessing Prebid.js functionality.

```tsx
const { pbjs, refresh } = usePrebid();
```

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| pbjs | object | Direct access to Prebid.js instance |
| refresh | function | Function to refresh all ad units |

## Best Practices

1. **Initialization**: Always wrap your app or the part of your app that contains ads with `PrebidProvider`.

2. **Ad Unit Codes**: Use unique, descriptive codes for each ad unit.

3. **Performance**: 
   - Don't place too many ad units on a single page
   - Consider lazy loading ads below the fold
   - Use appropriate timeout values for your users' connection speeds

4. **Testing**: 
   - Test with different bidders
   - Verify bid responses in the browser console
   - Check for proper ad rendering

## Common Issues

### Ads Not Displaying

1. Verify that Google Ad Manager script is loaded
2. Check browser console for errors
3. Ensure ad unit codes are unique
4. Verify bidder configurations

### Poor Performance

1. Reduce number of concurrent ad requests
2. Adjust timeout values
3. Implement lazy loading for below-the-fold ads

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## About the Author

This package is maintained by [Diogo Arrais](https://diogoarrais.com/), who writes extensively about ad technology and web development. For more insights about Prebid.js and header bidding, check out the [Understanding Prebid Header Bidding](https://diogoarrais.com/blog/understanding-prebid-header-bidding) guide.

## License

ISC

## Support

For issues and feature requests, please [open an issue](https://github.com/dioogarrais/prebid-react/issues) on GitHub.