ad-engine

# Ad Engine — Facebook Ads Deployment Assemble ads from database components and deploy to Facebook. Reads from Supabase `ad_components` + `messages` tables, assembles full ad copy, uploads images, and creates Campaign → Ad Set → Ad in Facebook Ads Manager. ## First-Time Setup **1. Facebook prerequisites (one-time, manual):** - Facebook Business Manager account - Ad Account created - Facebook Page connected - Facebook Developer App with `ads_management` permission - Long-lived access token (generate at developers.facebook.com) **2. Store credentials:** ```bash python3 scripts/fb_deploy.py --setup ``` Prompts for access token, ad account ID, and page ID. Validates against FB API and saves to `~/.config/ad-engine/fb_config.json`. ## Usage **Preview assembled ads (no deployment):** ```bash # Preview a single ad python3 scripts/fb_deploy.py --preview --message-id 8555 # Preview all draft ads for a campaign python3 scripts/fb_deploy.py --preview --campaign-id 43 # Preview as JSON python3 scripts/fb_deploy.py --preview --campaign-id 43 --json ``` **Deploy a single ad:** ```bash python3 scripts/fb_deploy.py --deploy \ --message-id 8556 \ --image /path/to/security-audit-ad.png \ --landing-url "https://calendly.com/your-link" \ --objective messages ``` **Deploy all draft ads for a campaign:** ```bash python3 scripts/fb_deploy.py --deploy \ --campaign-id 43 \ --image-dir /path/to/ad-images/ \ --landing-url "https://calendly.com/your-link" \ --objective messages ``` **Dry run (preview what would be created):** ```bash python3 scripts/fb_deploy.py --deploy \ --campaign-id 43 \ --image-dir /path/to/images/ \ --landing-url "https://calendly.com/link" \ --dry-run ``` **Check deployed ad status + live metrics:** ```bash python3 scripts/fb_deploy.py --status --campaign-id 43 ``` ## Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `--preview` | One of | Preview assembled ads without deploying | | `--deploy` | these | Deploy ads to Facebook | | `--status` | three | Check status of deployed ads | | `--setup` | | Configure Facebook credentials | | `--message-id` | For single | Specific message ID to preview/deploy | | `--campaign-id` | For batch | All draft ads in a campaign | | `--image` | Deploy single | Image file path | | `--image-dir` | Deploy batch | Directory of images (matched by angle name in filename) | | `--landing-url` | Deploy | Booking/landing page URL | | `--objective` | No | `leads` (default), `messages`, or `link_clicks` | | `--dry-run` | No | Preview deployment without creating anything | | `--json` | No | Output as JSON | ## Image Naming Convention When using `--image-dir` for batch deploy, name images by angle: ``` security-audit-ad.png → matches angle "security_audit" setup-is-hell-ad.png → matches angle "setup_is_hell" dm-trigger-checklist.png → matches angle "dm_trigger" anti-wrapper-graveyard.png → matches angle "anti_wrapper" ``` ## How It Works 1. Reads message from Supabase `messages` table (content_type = 'fb_ad') 2. Reads component references from message's `extra_data.components` 3. Resolves component keys → actual text from `ad_components` table 4. Slots components into framework template using `{{merge_tags}}` 5. Uploads image to Facebook → gets image_hash 6. Creates Campaign (if new) → Ad Set (if new) → Ad Creative → Ad 7. Updates message status to 'deployed' with FB IDs stored in extra_data ## Database Schema See `AD_ENGINE_SPEC.md` for full schema documentation. ## Dependencies - `psycopg2-binary` — Supabase Postgres connection - `facebook-business` — Facebook Marketing API SDK - `requests` — HTTP client - All auto-installed on first run.