meta-ad-creatives

# Meta Ad Creatives

Track creative performance and hit rates across multiple Meta Ads accounts.

## What This Skill Does

- Calculate **hit rates** (% of creatives meeting performance benchmarks)
- Track multiple metrics: **CPT** (cost per trial), **CPI** (cost per install), **IPM** (installs per mille), **ROAS**
- Compare performance across **multiple accounts**
- Store **historical data** for trend analysis
- Identify **winning creatives** vs underperformers
- Support **currency conversion** for international accounts

## Setup

### 1. Environment Variables

```bash
FACEBOOK_ACCESS_TOKEN=your_token_here
FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
```

### 2. Accounts Configuration

Create `accounts_config.json`:

```json
{
  "accounts": {
    "ClientName": {
      "account_id": "123456789",
      "filter": "CampaignNameFilter",
      "geo_filter": "US",
      "benchmark_value": 100,
      "benchmark_display": "CPT < $100",
      "active": true
    }
  }
}
```

Configuration fields:
- `account_id`: Meta Ad Account ID (without `act_` prefix)
- `filter`: Campaign name filter (optional)
- `geo_filter`: Geographic filter like "US" (optional)
- `benchmark_value`: CPT threshold for "winning" creatives
- `benchmark_display`: Human-readable benchmark description

## Usage

### Get Hit Rates for Current Month

```python
from scripts.meta_ad_creatives import get_all_hit_rates

data = get_all_hit_rates(month_offset=0)
print(f"Overall hit rate: {data['totals']['hit_rate']}%")
for account in data['accounts']:
    print(f"  {account['account_name']}: {account['hit_rate']}%")
```

### Get Hit Rates for Previous Months

```python
# Last month
data = get_all_hit_rates(month_offset=-1)

# Two months ago
data = get_all_hit_rates(month_offset=-2)
```

### Get All-Time Aggregated Data

```python
data = get_all_hit_rates(all_time=True)
```

### Get Individual Ad Performance

```python
from scripts.meta_ad_creatives import get_individual_ads

# All ads for an account...