# Facebook Ad Library API Setup Guide

This guide will help you set up the Facebook Ad Library API integration with your content evaluation platform.

## Prerequisites

1. **Facebook Developer Account**: You need a Facebook Developer account
2. **Identity Verification**: Required for political/issue ads access
3. **Business Verification**: May be required for certain features

## Step 1: Create Facebook Developer Account

1. Go to [developers.facebook.com](https://developers.facebook.com)
2. Click "Get Started" and log in with your Facebook account
3. Complete the developer registration process
4. Agree to the Platform Policy and Terms

## Step 2: Create a Facebook App

1. In your Facebook Developer dashboard, click "My Apps"
2. Click "Create App"
3. Choose "Business" as the app type
4. Fill in the app details:
   - **App Name**: Your app name (e.g., "Content Evaluator")
   - **Contact Email**: Your email address
   - **Business Account**: Select or create a business account

## Step 3: Get App Credentials

1. In your app dashboard, go to "Settings" → "Basic"
2. Copy your **App ID** and **App Secret**
3. Keep these credentials secure - you'll need them for configuration

## Step 4: Identity Verification (Required for Political Ads)

1. Go to [facebook.com/id](https://facebook.com/id)
2. Complete the identity verification process:
   - Upload government-issued ID (passport, driver's license, or national ID)
   - Provide your legal name and address
   - Wait for approval (typically 24-48 hours)

## Step 5: Configure Your Application

1. Copy the `.env.example` file to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit the `.env` file with your credentials:
   ```bash
   # Facebook Ad Library API Configuration
   FACEBOOK_APP_ID=your_app_id_here
   FACEBOOK_APP_SECRET=your_app_secret_here

   # Application Configuration
   SECRET_KEY=your-unique-secret-key-here
   ```

3. Never commit the `.env` file to version control!

## Step 6: Test the Integration

1. Start your application:
   ```bash
   python ez_viewer.py
   ```

2. Navigate to the Facebook Ads section
3. Click "Test Facebook API Connection"
4. If successful, you should see connection confirmation

## API Limitations

### Geographic Restrictions
- **Political/Issue Ads**: Available globally for the past 7 years
- **All Ads**: Only available for UK, EU, and Brazil in the past year

### Rate Limits
- **200 requests per hour** per app
- Rate limiting is automatically handled by the client

### Data Availability
- The API provides **metadata only** (text, targeting, spend ranges)
- **Creative assets** (images/videos) are not directly downloadable
- Ad snapshots are provided as URLs to Facebook's ad viewer

## Supported Search Parameters

### Countries
- `US` - United States
- `GB` - United Kingdom
- `BR` - Brazil
- `EU` - European Union
- `ALL` - Global (political ads only)

### Ad Types
- `ALL` - All available ads
- `POLITICAL_AND_ISSUE_ADS` - Political and issue ads only

### Media Types
- `ALL` - All media types
- `VIDEO` - Video ads only
- `IMAGE` - Image ads only

## Troubleshooting

### Common Errors

**"OAuthException: An unknown error has occurred" (Code 1)**
- This means your app doesn't have Ad Library API permissions
- **SOLUTION**: Your app needs special approval from Facebook
- Complete identity verification at [facebook.com/id](https://facebook.com/id)
- Go to App Review → Permissions and Features → Request "ads_read" permission
- Explain your use case: "Content evaluation platform for brand compliance"
- **TEMPORARY WORKAROUND**: Try searching only political ads (they have broader access)

**"Authorization Error"**
- Check that your App ID and App Secret are correct
- Ensure identity verification is complete
- Verify your app has the necessary permissions

**"No Results Found"**
- Political/issue ads have broader availability than regular ads
- Try different search terms or expand date ranges
- Check that you're searching in supported countries

**"Rate Limit Exceeded"**
- The system automatically handles rate limiting
- If you hit limits frequently, consider reducing search frequency
- Rate limits reset every hour

### App Review Process

Facebook requires manual approval for Ad Library API access:

1. **Complete identity verification** (required first step)
2. **Submit app for review** with these details:
   - Use Case: Content evaluation and brand compliance monitoring
   - Explain how you'll use ad data responsibly
   - Provide screenshots of your app interface
   - Demonstrate legitimate business need

3. **Review timeline**: 7-14 business days
4. **During review**: Test with political ads only

### Getting Help

1. **Facebook Developer Support**: [developers.facebook.com/support](https://developers.facebook.com/support)
2. **Ad Library API Documentation**: [facebook.com/ads/library/api](https://facebook.com/ads/library/api)
3. **Community Forums**: Facebook Developer Community

## Usage Tips

1. **Start Small**: Begin with political/issue ads as they have broader availability
2. **Use Specific Terms**: More specific search terms yield better results
3. **Check Date Ranges**: Recent ads have better availability
4. **Monitor Rate Limits**: The dashboard shows remaining API calls

## Privacy and Compliance

- All data accessed is **publicly available** through Facebook's Ad Library
- No private user data is accessed
- Follow Facebook's Platform Policy and Terms of Service
- Consider data retention policies for downloaded ad information

## Next Steps

Once configured, you can:
1. Search for Facebook ads by keyword, advertiser, or date range
2. View ad metadata including spend, impressions, and targeting
3. Process ad text content through your evaluation pipeline
4. Generate compliance reports combining uploaded media and Facebook ads

For advanced features like automated monitoring or custom integrations, refer to the API documentation.