Ad Engine
by @aces1up
Assemble modular ads from Supabase components and deploy to Facebook Ads Manager via the Marketing API. Supports preview, single/batch deploy, and status tra...
clawhub install ad-engineπ About This Skill
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):
ads_management permission2. Store credentials:
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):
# Preview a single ad
python3 scripts/fb_deploy.py --preview --message-id 8555Preview all draft ads for a campaign
python3 scripts/fb_deploy.py --preview --campaign-id 43Preview as JSON
python3 scripts/fb_deploy.py --preview --campaign-id 43 --json
Deploy 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 messages
Deploy 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 messages
Dry 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-run
Check deployed ad status + live metrics:
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 connectionfacebook-business β Facebook Marketing API SDKrequests β HTTP clientπ‘ Examples
Preview assembled ads (no deployment):
# Preview a single ad
python3 scripts/fb_deploy.py --preview --message-id 8555Preview all draft ads for a campaign
python3 scripts/fb_deploy.py --preview --campaign-id 43Preview as JSON
python3 scripts/fb_deploy.py --preview --campaign-id 43 --json
Deploy 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 messages
Deploy 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 messages
Dry 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-run
Check deployed ad status + live metrics:
python3 scripts/fb_deploy.py --status --campaign-id 43