🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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...

Versionv1.0.0
Downloads504
TERMINAL
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):

  • 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:

    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 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:

    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 connection
  • facebook-business β€” Facebook Marketing API SDK
  • requests β€” HTTP client
  • All auto-installed on first run.
  • πŸ’‘ Examples

    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 --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