# Ad Copy Frameworks

Frameworks for writing ad copy variants and structuring A/B tests.

## Hook Patterns

The hook is the first line of ad copy — it determines whether someone keeps reading. Each pattern works differently depending on audience and offer.

### Number-Led Hook
Leads with a specific, concrete number. High CTR when the number is surprising or aspirational.

- "Cut your onboarding time from 3 weeks to 3 days"
- "47% of teams switch within the first month"
- "Save 12 hours per week on reporting"

### Question Hook
Opens with a question that the target audience would answer "yes" to. Creates immediate relevance.

- "Still manually reconciling invoices every month?"
- "What if your team could ship 2x faster?"
- "Tired of tools that promise AI but deliver spreadsheets?"

### Pain-Point Hook
Names a specific frustration the audience experiences. Works best for problem-aware audiences.

- "Your CRM shouldn't need a full-time admin"
- "Scattered tools. Missed deadlines. Sound familiar?"
- "Manual data entry is costing you more than you think"

### Benefit-First Hook
Leads with the outcome, not the problem. Works for solution-aware audiences.

- "Automate your entire onboarding workflow in one click"
- "Get real-time insights without writing a single query"
- "Ship landing pages in minutes, not sprints"

### Social Proof Hook
Opens with credibility — customer results, user count, or testimonials.

- "Join 10,000+ teams that ditched manual reporting"
- "'We cut our CAC by 40% in the first quarter' — [Customer]"
- "Rated #1 on G2 for ease of use"

## Body Frameworks

### Problem-Agitate-Solve (PAS)
1. State the problem
2. Amplify the pain
3. Present the solution

Best for: Cold audiences, pain-point messaging

### Feature-Advantage-Benefit (FAB)
1. Name the feature
2. Explain what it enables
3. State the outcome for the user

Best for: Product-aware audiences, feature launches

### Before-After-Bridge (BAB)
1. Describe current state (before)
2. Describe desired state (after)
3. Show how to get there (bridge = your product)

Best for: Aspirational messaging, transformation offers

## CTA Types

| CTA | Best For | Tone |
|-----|----------|------|
| Learn More | Top of funnel, awareness | Low commitment |
| Shop Now | E-commerce, product pages | Direct, transactional |
| Get Started | SaaS, free trial | Action-oriented |
| Try Free | Freemium, risk removal | Low barrier |
| Book a Demo | Enterprise, high-ticket | Consultative |
| Sign Up | Membership, newsletters | Simple commitment |
| Get Offer | Promotions, limited time | Urgency |
| Download | Lead magnets, resources | Value exchange |

Match CTA to funnel stage. Don't use "Shop Now" for awareness campaigns or "Learn More" for retargeting.

## Variant Generation Strategy

### The One-Variable Rule

Each variant should change exactly one element from the control. This lets you attribute performance differences to specific changes.

**Example from a winning control ad:**
> Hook: "Cut your onboarding time from 3 weeks to 3 days"
> Body: Customer quote about time savings
> CTA: "Get Started Free"

**Variant set (8 variants):**

Hook variants (change hook, keep body + CTA):
1. Different metric: "Reduce support tickets by 60% in 30 days"
2. Different metric: "Onboard new hires in hours, not weeks"
3. Question-based: "What if onboarding took 3 days instead of 3 weeks?"
4. Pain-point: "3-week onboarding is costing you your best hires"

Body variants (change body, keep hook + CTA):
5. Feature highlight instead of social proof
6. Stat-driven instead of quote-driven

CTA variants (change CTA, keep hook + body):
7. "Book a Demo" instead of "Get Started Free"
8. "See How It Works" instead of "Get Started Free"

### Variant Grouping

Always group and label variants by what's being tested:

```
GROUP A: Hook Testing (4 variants)
  - A1: Number-led (different metric)
  - A2: Number-led (different framing)
  - A3: Question-based hook
  - A4: Pain-point hook

GROUP B: Body Testing (2 variants)
  - B1: Feature-focused body
  - B2: Data-driven body

GROUP C: CTA Testing (2 variants)
  - C1: Higher-commitment CTA
  - C2: Curiosity-driven CTA
```

### A/B Test Pairing

Pair variants for testing so each pair isolates one variable:

| Test | Control Element | Test Element | Variable |
|------|----------------|-------------|----------|
| Test 1 | Number-led hook | Question hook | Hook type |
| Test 2 | Customer quote body | Feature body | Body approach |
| Test 3 | "Get Started Free" CTA | "Book a Demo" CTA | CTA commitment level |

### Test Priority

Prioritize testing based on which element has the most variance in existing performance data:

1. **Hooks first** — highest impact on CTR. If top ads have wildly different hook styles, test hooks.
2. **Body second** — impacts conversion rate. Test if CTR is stable but CVR varies.
3. **CTA last** — smallest effect size. Test when hook and body are optimized.

## Analyzing Existing Ad Performance

When the user provides performance data from existing ads:

1. **Correlate metrics with copy elements** — which hook types get highest CTR? Which body styles drive CVR?
2. **Identify winning patterns** — not just the best ad, but what pattern the top 3-5 ads share
3. **Find the gap** — what hasn't been tested yet? If all top ads use number-led hooks, a question hook is worth testing
4. **Preserve winners, vary strategically** — new variants should keep the winning pattern and change one thing

## Output Format

When delivering ad copy variants, always include:

1. Variants grouped by test variable (hook, body, CTA)
2. Annotation showing which winning element each variant preserves
3. Recommended test priority
4. Platform-specific formatting (character limits respected)
5. A/B test pairings showing which variants to test against each other

# Brand Extraction

Extract brand identity from a website for use in ad creative generation.

## Single-Call Workflow

`firecrawl_branding_extract` extracts branding data, downloads the logo, and captures a screenshot in one call:

```python
brand = firecrawl_branding_extract(url="https://example.com")
```

## Return Shape

```
brand.logo.file_id        -- File ID of the saved logo (pass to image gen)
brand.logo.path           -- Storage path of the saved logo
brand.logo.description    -- "Brand logo for Example"

brand.screenshot.file_id  -- File ID of the saved screenshot (pass to image gen)
brand.screenshot.path     -- Storage path of the saved screenshot
brand.screenshot.description -- AI description of the page

brand.branding            -- Dict with full brand data:
  .colors                 -- primary, accent, background, text (hex codes)
  .typography             -- fonts, font families, sizes
  .spacing                -- base units, border radius
  .components             -- button styles, input styles
  .personality            -- brand tone and voice
  .designSystem           -- overall design system summary
  .confidence             -- extraction confidence scores

brand.file                -- Saved branding JSON file (NOT an image)
```

**Critical:** `brand.file` is the JSON data file. Never pass it to image gen tools. Only `brand.logo.file_id` and `brand.screenshot.file_id` are images.

## Using Brand Assets in Image Generation

Always pass **both logo and screenshot** as reference images. SVG logos are automatically converted to PNG by the extraction tool, so always include the logo regardless of the original format.

```python
reference_images = [brand.logo.file_id, brand.screenshot.file_id]
```

The logo provides brand mark consistency. The screenshot shows the actual product UI so the model can derive both the visual style and generate realistic product shots.

### Default creative pattern (SaaS / product ads)

By default, compose: **logo + headline + realistic product screenshot**. Describe the product screenshot based on `brand.screenshot.description`, not guessed.

```python
images_generate(
    requests=[{
        "prompt": (
            "Social media ad creative for [company name]. "
            "Top: the [company] logo. "
            "Headline: '[headline]'. "
            "Below: a clean, realistic product screenshot of [describe actual UI from brand.screenshot.description]. "
            "Match the brand style from the references."
        ),
        "reference_images": reference_images
    }],
    quality="high"
)
```

This is the recommended default. If the user asks for a different creative direction (lifestyle, illustration, abstract, etc.), follow their lead — the references still provide brand consistency.

## Using Brand Data for Ad Copy

The extracted brand data is primarily useful for **copy**, not image prompts.

### Copy Tone from Brand Personality

Use `brand.branding["personality"]` to set the voice for ad copy:

- Professional → authoritative, data-driven, clear value props
- Playful → conversational, emoji-friendly, informal CTAs
- Technical → precise language, feature-focused, specs matter
- Luxury → aspirational, exclusive language, understated claims

### Colors in Copy (not image prompts)

Brand colors inform copy context (e.g., knowing the brand is a fintech vs. a kids' toy brand), but do NOT paste hex codes into image prompts — the reference images already contain the actual colors.

## Cached Results

`firecrawl_branding_extract` caches results by domain. Subsequent calls for the same domain return cached data without re-fetching. Use `refresh=True` to force a fresh extraction:

```python
brand = firecrawl_branding_extract(url="https://example.com", refresh=True)
```

# Google Ads Creatives

Specs and guidelines for generating Google Ads creative assets.

## Responsive Search Ads (RSAs)

RSAs are Google's primary text ad format. You provide multiple headlines and descriptions; Google assembles combinations and optimizes.

### Asset Requirements

| Asset | Count | Character Limit | Notes |
|-------|-------|----------------|-------|
| Headlines | Up to 15 | 30 characters each | At least 3 required, 15 recommended |
| Descriptions | Up to 4 | 90 characters each | At least 2 required, 4 recommended |

### Headline Rules

- Max 30 characters including spaces
- No exclamation marks in headlines (Google policy)
- No excessive capitalization (e.g., "FREE SHIPPING" is rejected)
- Include the target keyword in at least 2-3 headlines
- Each headline should be able to stand alone (Google may show any combination)
- Don't repeat the same message across headlines — each should offer a different angle

### Headline Strategy (15 headlines)

Distribute across these categories:

| Category | Count | Examples |
|----------|-------|---------|
| Keyword-focused | 3-4 | Include primary and secondary keywords |
| Benefit-driven | 3-4 | "Save 10 Hours Per Week", "Reduce Costs by 40%" |
| Feature-specific | 2-3 | "AI-Powered Analytics", "Real-Time Dashboards" |
| CTA-oriented | 2-3 | "Start Free Trial Today", "Get a Demo" |
| Social proof | 1-2 | "Trusted by 5,000+ Teams", "4.8★ on G2" |
| Urgency/offer | 1-2 | "Limited Time Offer", "Free for 14 Days" |

### Description Rules

- Max 90 characters including spaces
- Expand on what headlines introduce — don't repeat them
- Include a clear value proposition
- End with a CTA when possible
- First description is shown most often — make it strongest

### Description Strategy (4 descriptions)

1. **Primary value prop** — the core reason to click (shown most often)
2. **Feature + benefit** — specific capability and its outcome
3. **Social proof / credibility** — results, ratings, customer count
4. **CTA + offer** — what they get and how to get it

### Pin Positions

You can pin specific headlines / descriptions to positions:

- **Pin sparingly** — pinning reduces Google's optimization ability
- **Pin your brand** to Headline 1 if brand recognition matters
- **Pin your CTA** to Headline 3 to ensure it always appears
- Never pin all positions — defeats the purpose of RSAs

## Display Ads

### Responsive Display Ads

Google's responsive display format assembles your assets into ads across the Display Network.

| Asset | Spec | Count |
|-------|------|-------|
| Landscape image | 1200x628 (1.91:1) | Up to 15 |
| Square image | 1200x1200 (1:1) | Up to 15 |
| Logo (landscape) | 1200x300 (4:1) | Up to 5 |
| Logo (square) | 1200x1200 (1:1) | Up to 5 |
| Short headline | 30 characters | Up to 5 |
| Long headline | 90 characters | 1 |
| Description | 90 characters | Up to 5 |
| Business name | 25 characters | 1 |

### Image Guidelines

- File size: max 5MB
- No text overlays covering more than 20% of the image
- High contrast between subject and background
- Product or service should be clearly visible
- Avoid borders or excessive whitespace

### Generating Display Ad Images

Every creative needs three layers: **brand** (logo), **copy** (headline), and **product** (realistic screenshot). Use `brand.screenshot.description` to describe the actual product UI.

Square (1:1):

```python
images_generate(
    requests=[{
        "prompt": (
            "Display ad creative for [company name]. "
            "Logo at top. Headline: '[headline]'. "
            "Below: realistic product screenshot of [describe actual UI from brand.screenshot.description]. "
            "Match the brand style from the references."
        ),
        "reference_images": [brand.logo.file_id, brand.screenshot.file_id]
    }],
    quality="high"
)
```

Landscape (1.91:1):

```python
images_generate(
    requests=[{
        "prompt": (
            "Wide display ad creative for [company name]. "
            "Logo at top left. Headline: '[headline]'. "
            "Right side: realistic product screenshot of [describe actual UI]. "
            "Match the brand style from the references."
        ),
        "reference_images": [brand.logo.file_id, brand.screenshot.file_id]
    }],
    quality="high"
)
```

## Performance Max

Performance Max campaigns use all Google surfaces. Asset requirements are a superset of RSA + Display.

### Additional Assets for PMax

| Asset | Spec |
|-------|------|
| YouTube video | Various aspect ratios, 10s-60s recommended |
| Portrait image | 960x1200 (4:5) |
| Call to action | Select from predefined list |
| Sitelinks | Up to 4 |

### Asset Group Strategy

- Each asset group should target a distinct audience theme
- Provide maximum assets per group for best optimization
- Use high-quality images that represent the product / service
- Include both lifestyle and product-focused images

## Google Ads Copy Rules

### Policies to Follow

- No misleading claims or exaggeration
- No exclamation marks in headlines
- No ALL CAPS (except standard acronyms like "AI", "CRM")
- No phone numbers in ad text
- No trademarked terms without authorization
- Prices and discounts must be accurate and current
- Landing page must match the ad's offer

### Quality Score Factors

Ad copy directly impacts Quality Score:

1. **Relevance** — copy must match the target keyword intent
2. **Expected CTR** — compelling copy improves predicted click-through
3. **Landing page experience** — ad promise must be fulfilled on the page

Write copy that closely matches what users are searching for and what the landing page delivers.

# Meta Ads Creatives

Specs and guidelines for generating Meta (Facebook / Instagram) ad creative assets.

## Text Specs

### Primary Text

The main body text that appears above the image / video.

| Metric | Limit |
|--------|-------|
| Visible before "See more" | ~125 characters |
| Maximum length | 2,200 characters |
| Recommended | 125 characters or fewer |

The first 125 characters are critical — everything after is truncated behind "See more". Front-load the hook and value proposition.

### Headline

Appears below the image, next to the CTA button.

| Metric | Limit |
|--------|-------|
| Recommended | 40 characters |
| Maximum | 255 characters (truncated on most placements) |

Keep headlines punchy. They compete with the CTA button for attention.

### Description

Appears below the headline on some placements (not always shown).

| Metric | Limit |
|--------|-------|
| Recommended | 30 characters |
| Maximum | 125 characters |

Don't rely on the description for critical info — it's often hidden.

## Image Specs by Placement

### Feed Ads (Facebook + Instagram)

| Spec | Requirement |
|------|-------------|
| Aspect ratio | 1:1 (recommended) or 4:5 |
| Resolution | 1080x1080 (1:1) or 1080x1350 (4:5) |
| File type | JPG or PNG |
| Max file size | 30MB |
| Text overlay | Less than 20% of image area |

4:5 takes more vertical space in the feed, increasing visibility. Use 1:1 for broad compatibility.

### Story / Reel Ads (Facebook + Instagram)

| Spec | Requirement |
|------|-------------|
| Aspect ratio | 9:16 |
| Resolution | 1080x1920 |
| File type | JPG or PNG (image), MP4 or MOV (video) |
| Max file size | 30MB (image), 4GB (video) |
| Safe zone | Keep key content in center 1080x1420 area |

Leave ~250px clear at top (profile bar) and bottom (CTA bar).

### Right Column (Facebook Desktop)

| Spec | Requirement |
|------|-------------|
| Aspect ratio | 1:1 |
| Resolution | 1080x1080 |
| Note | Small placement, image must be clear at small size |

### Audience Network

| Spec | Requirement |
|------|-------------|
| Aspect ratio | 9:16 |
| Resolution | 1080x1920 |

## Carousel Ads

Carousel ads display up to 10 scrollable cards, each with its own image, headline, description, and link.

### Card Specs

| Spec | Requirement |
|------|-------------|
| Cards | 2-10 |
| Aspect ratio | 1:1 (required for carousel) |
| Resolution | 1080x1080 per card |
| Headline per card | 40 characters recommended |
| Description per card | 20 characters recommended |
| Link per card | Each card can link to a different URL |

### Carousel Strategies

- **Product showcase** — each card features a different product
- **Feature walkthrough** — each card explains one feature / benefit
- **Story arc** — cards tell a sequential story that builds to a CTA
- **Social proof series** — each card shows a different testimonial
- **Before / after** — alternate between problem and solution cards

### Generating Carousel Images

Generate all cards in a single batch. Each card should have the brand logo, a short headline for that card's feature, and a relevant product screenshot.

```python
images_generate(
    requests=[
        {"prompt": "Card 1 for [company]. Logo at top. Headline: '[feature 1]'. Below: product screenshot showing [feature 1 UI]. Match brand style.", "reference_images": [logo_id, screenshot_id]},
        {"prompt": "Card 2 for [company]. Logo at top. Headline: '[feature 2]'. Below: product screenshot showing [feature 2 UI]. Same style as card 1.", "reference_images": [logo_id, screenshot_id]},
        {"prompt": "Card 3 for [company]. Logo at top. Headline: '[feature 3]'. Below: product screenshot showing [feature 3 UI]. Same style as card 1.", "reference_images": [logo_id, screenshot_id]},
    ],
    quality="high"
)
```

## Creative Best Practices

### Image Creative

- **Show the product in use** — context beats isolation
- **One clear focal point** — don't overcrowd the image
- **Contrast with the feed** — bright images stand out against grey / white feeds
- **Brand colors in the image** — not just in copy, in the visual itself
- **Faces perform well** — human faces increase engagement
- **Avoid stock photo aesthetics** — authenticity outperforms polish

### Copy + Creative Alignment

The image and copy must tell the same story:

- If the hook mentions a number, the image should reinforce it
- If the body talks about ease, the image should feel simple and clean
- CTA in copy should match the CTA button selected

### Platform Differences

**Facebook Feed:**
- Longer primary text can work (users scroll slower)
- Link description is shown more often
- Right column placements need simple, clear images

**Instagram Feed:**
- Visual quality matters more than copy length
- 4:5 aspect ratio takes maximum screen real estate
- Hashtags in primary text can extend reach

**Instagram Stories:**
- Full-screen vertical format
- First 3 seconds determine whether users swipe past
- Swipe-up / link CTA must be visually prompted
- Keep text minimal — the visual does the work

## Generating Meta Ad Images

Every creative needs three layers: **brand** (logo), **copy** (headline + subline), and **product** (realistic screenshot of the actual app). Use `brand.screenshot.description` to understand what the product UI looks like.

### Feed Creative (1:1)

```python
images_generate(
    requests=[{
        "prompt": (
            "Social media ad creative for [company name]. "
            "Top: the [company] logo. "
            "Headline: '[headline from ad copy or site hero text]'. "
            "Below: a clean, realistic product screenshot of [describe actual UI from brand.screenshot.description]. "
            "Match the brand style from the references."
        ),
        "reference_images": [brand.logo.file_id, brand.screenshot.file_id]
    }],
    quality="high"
)
```

### Story Creative (9:16)

```python
images_generate(
    requests=[{
        "prompt": (
            "Vertical story ad creative for [company name]. "
            "Top: the [company] logo. "
            "Headline: '[headline]'. "
            "Below: a realistic product screenshot of [describe actual UI]. "
            "Match the brand style from the references."
        ),
        "reference_images": [brand.logo.file_id, brand.screenshot.file_id]
    }],
    quality="high"
)
```

### Text-Heavy Creative (headlines in image)

When the creative needs large, readable text baked into the image, use Nano Banana for better text rendering:

```python
images_generate(
    requests=[{
        "prompt": (
            "Ad creative for [company name]. "
            "Logo at top. Large headline: '[headline]'. "
            "Below: realistic product screenshot of [describe actual UI]. "
            "Match the brand style from the references."
        ),
        "reference_images": [brand.logo.file_id, brand.screenshot.file_id]
    }],
    aspect_ratio="1:1",
)
```