- name
- ad-engine
- description
- Assemble modular ads from Supabase components and deploy to Facebook Ads Manager via the Marketing API. Supports preview, single/batch deploy, and status tracking. Uses ad_components table for A/B testing at scale.
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_managementpermission - Long-lived access token (generate at developers.facebook.com)
2. Store credentials:
python3 scripts/fb_deploy.py --setupPrompts 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):
# 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 --jsonDeploy a single ad:
python3 scripts/fb_deploy.py --deploy \
--message-id 8556 \
--image /path/to/security-audit-ad.png \
--landing-url "https://calendly.com/your-link" \
--objective messagesDeploy all draft ads for a campaign:
python3 scripts/fb_deploy.py --deploy \
--campaign-id 43 \
--image-dir /path/to/ad-images/ \
--landing-url "https://calendly.com/your-link" \
--objective messagesDry run (preview what would be created):
python3 scripts/fb_deploy.py --deploy \
--campaign-id 43 \
--image-dir /path/to/images/ \
--landing-url "https://calendly.com/link" \
--dry-runCheck deployed ad status + live metrics:
python3 scripts/fb_deploy.py --status --campaign-id 43Parameters
| 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
- Reads message from Supabase
messagestable (content_type = 'fb_ad') - Reads component references from message's
extra_data.components - Resolves component keys → actual text from
ad_componentstable - Slots components into framework template using
{{merge_tags}} - Uploads image to Facebook → gets image_hash
- Creates Campaign (if new) → Ad Set (if new) → Ad Creative → Ad
- 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 connectionfacebook-business— Facebook Marketing API SDKrequests— HTTP client- All auto-installed on first run.