jake/clawdbot-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
clawdbot-workspace/FB_ADS_FIELD_REFERENCE.md

329 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Facebook Ads CSV Bulk Upload - Complete Field Reference
## 📚 Table of Contents
- [Campaign Level Fields](#campaign-level-fields)
- [Ad Set Level Fields](#ad-set-level-fields)
- [Ad Level Fields](#ad-level-fields)
- [Advanced Features](#advanced-features)
- [Validation Rules](#validation-rules)
- [Common Use Cases](#common-use-cases)
---
## Campaign Level Fields
### Required Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Campaign Name` | Name of your campaign | Any string (max 250 chars) | "Q1 2026 Product Launch" |
| `Campaign Objective` | Campaign goal | OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION, OUTCOME_AWARENESS | OUTCOME_TRAFFIC |
| `Buying Type` | Auction type | AUCTION, RESERVATION | AUCTION |
| `Campaign Status` | Initial campaign state | ACTIVE, PAUSED | ACTIVE |
### Optional Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Campaign Budget Optimization` | Enable CBO | TRUE, FALSE | FALSE |
| `Campaign Budget` | Total campaign budget (only if CBO=TRUE) | Positive number | 1000 |
| `Campaign Bid Strategy` | How to bid | LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST | LOWEST_COST_WITHOUT_CAP |
| `Campaign Spend Limit` | Max spend across campaign | Positive number | 5000 |
---
## Ad Set Level Fields
### Required Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Ad Set Name` | Name of ad set | Any string | "Cold Traffic - Tech Enthusiasts 18-35" |
| `Optimization Goal` | What to optimize for | LINK_CLICKS, LANDING_PAGE_VIEWS, IMPRESSIONS, REACH, OFFSITE_CONVERSIONS, THRUPLAY, POST_ENGAGEMENT | LINK_CLICKS |
| `Billing Event` | What you pay for | IMPRESSIONS, LINK_CLICKS, THRUPLAY | LINK_CLICKS |
| `Daily Budget` OR `Lifetime Budget` | Budget amount | Positive number (min $1/day) | 50.0 |
| `Ad Set Status` | Initial ad set state | ACTIVE, PAUSED | ACTIVE |
### Targeting Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Targeting Age Min` | Minimum age | 13-65 | 18 |
| `Targeting Age Max` | Maximum age | 13-65+ | 65+ |
| `Targeting Gender` | Gender targeting | All, Male, Female | All |
| `Targeting Locations` | Geographic targeting | Country names, states, cities (comma-separated) | "United States,Canada" |
| `Targeting Custom Audiences` | Custom audience IDs | Comma-separated IDs | "123456789,987654321" |
| `Targeting Excluded Custom Audiences` | Audiences to exclude | Comma-separated IDs | "111222333" |
| `Targeting Interests` | Interest targeting | Interest names (comma-separated) | "Technology,AI,Software" |
| `Targeting Behaviors` | Behavior targeting | Behavior names | "Tech Early Adopters" |
| `Targeting Languages` | Language codes | ISO language codes | "en,es,fr" |
### Placement Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Placements` | Placement selection | Automatic, Manual | Automatic |
| `Platform Positions` | Specific platforms (if Manual) | Facebook, Instagram, Messenger, Audience Network | "Facebook,Instagram" |
### Scheduling Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Start Date` | When to start | YYYY-MM-DD | 2026-02-15 |
| `End Date` | When to end (optional) | YYYY-MM-DD or blank | 2026-03-15 |
### Conversion Tracking (For Sales/Leads objectives)
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Promoted Object Pixel ID` | Meta Pixel ID | Numeric ID | 123456789012345 |
| `Promoted Object Custom Event Type` | Event to track | Purchase, Lead, CompleteRegistration, AddToCart, etc. | Purchase |
| `Optimization Window` | Conversion window | 1_DAY, 7_DAYS | 7_DAYS |
| `Attribution Setting` | Attribution window | 7_DAY_CLICK_1_DAY_VIEW, 1_DAY_CLICK, etc. | 7_DAY_CLICK_1_DAY_VIEW |
---
## Ad Level Fields
### Required Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Ad Name` | Name of the ad | Any string | "Hero Ad - Tech Audience v1" |
| `Ad Status` | Initial ad state | ACTIVE, PAUSED | ACTIVE |
| `Body` | Primary text | Any string (125 chars recommended) | "Transform your workflow with AI" |
| `Title` | Headline | Any string (40 chars max) | "Try OpenClaw Free Today" |
| `Link` | Destination URL | Valid URL | https://example.com |
### Creative Fields
**For Images:**
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Image Hash` | Use existing library image | Hash from library | abc123def456 |
| `Image File` | Upload new image | Filename to upload | hero_image_1080x1080.jpg |
**For Videos:**
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Video ID` | Use existing library video | ID from library | 123456789 |
| `Video File` | Upload new video | Filename to upload | product_demo.mp4 |
**Note:** Use either Hash/ID for existing assets OR File for new uploads. Don't fill both.
### Optional Fields
| Field | Description | Valid Values | Example |
|-------|-------------|--------------|---------|
| `Caption` | Link description | Any string | "Limited Time Offer" |
| `Call To Action` | CTA button | LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, GET_QUOTE, CONTACT_US, BOOK_NOW, APPLY_NOW, NO_BUTTON | LEARN_MORE |
| `Website URL` | Can differ from Link | Valid URL | https://example.com/promo |
| `Display Link` | Vanity URL shown | String | example.com/special |
### UTM Tracking
| Field | Description | Example |
|-------|-------------|---------|
| `UTM Source` | Traffic source | facebook |
| `UTM Medium` | Marketing medium | paid_social |
| `UTM Campaign` | Campaign identifier | q1_launch |
| `UTM Term` | Paid keywords (optional) | tech_audience |
| `UTM Content` | Ad variation identifier | hero_v1 |
---
## Advanced Features
### Dynamic Creative
Enable testing multiple variations of creative elements:
| Field | Purpose |
|-------|---------|
| `Dynamic Creative` | Set to TRUE to enable |
| `Additional Body 1-3` | Up to 3 extra primary text variations |
| `Additional Title 1-3` | Up to 3 extra headline variations |
| `Additional Image 1-2` | Up to 2 extra image variations |
Meta will automatically test combinations and optimize for best performers.
### Carousel Ads
Create multi-card carousel ads:
| Field Pattern | Example |
|---------------|---------|
| `Carousel Card [1-10] Title` | "Feature 1: Speed" |
| `Carousel Card [1-10] Body` | "10x faster than competitors" |
| `Carousel Card [1-10] Link` | https://example.com/feature1 |
| `Carousel Card [1-10] Image` | feature1.jpg |
Supports up to 10 cards per ad.
### Multi-Language (DLO)
Serve different languages automatically:
| Field Pattern | Example |
|---------------|---------|
| `Language [1-5] Code` | en, es, fr, de, etc. |
| `Language [1-5] Body` | Translated primary text |
| `Language [1-5] Title` | Translated headline |
| `Language [1-5] Link` | Language-specific landing page |
Meta serves the right language based on user's Facebook language setting.
### Partnership/Creator Ads
Use influencer content:
| Field | Description | Example |
|-------|-------------|---------|
| `Partnership Ad Code` | Code from creator | ABC123XYZ789 |
| `Creator Account ID` | Creator's Facebook/Instagram ID | 1234567890 |
### Existing Post IDs
Reuse posts to maintain social proof:
| Field | Description | Example |
|-------|-------------|---------|
| `Use Page Post` | Set to TRUE | TRUE |
| `Page Post ID` | ID of existing post | 123456789012345_67890 |
---
## Validation Rules
### Critical Constraints
1. **Budget Minimums**
- Daily Budget: Minimum $1.00
- Lifetime Budget: Minimum $1.00
2. **Date Format**
- Must be: YYYY-MM-DD
- Start Date cannot be in the past
- End Date must be after Start Date
3. **Age Targeting**
- Min Age: 13-65
- Max Age: 13-65 or "65+"
- Max must be >= Min
4. **Status Values**
- Only: ACTIVE or PAUSED
- Case-sensitive
5. **Objective-Specific Requirements**
- OUTCOME_SALES / OUTCOME_LEADS: Must include Pixel ID and Custom Event Type
- OUTCOME_TRAFFIC: Requires valid destination URL
6. **File Uploads**
- Images: JPG, PNG (max 30MB, 1080x1080px recommended)
- Videos: MP4, MOV (max 4GB, under 240 min)
- File names cannot contain spaces or special characters (use underscores)
7. **Creative Requirements**
- Must provide EITHER Image Hash/Video ID OR Image File/Video File
- Cannot leave creative fields entirely blank
- Primary text: 125 characters recommended (max 500)
- Headline: 40 characters max
- Link description: 30 characters max
---
## Common Use Cases
### 1. Simple Link Click Campaign
**Objective:** Drive traffic to website
**Required Fields:** Campaign Name, Objective (TRAFFIC), Ad Set Name, Daily Budget, Ad Name, Body, Title, Link, Image File
**Budget:** $50/day minimum recommended
### 2. Conversion Campaign
**Objective:** Track purchases/leads
**Additional Required:** Pixel ID, Custom Event Type, Optimization Goal (OFFSITE_CONVERSIONS)
**Budget:** $100/day minimum recommended
### 3. Creative Testing (Dynamic Creative)
**Setup:** Set Dynamic Creative = TRUE
**Fill:** Main creative + Additional Body 1-3, Additional Title 1-3, Additional Image 1-2
**Result:** Meta tests all combinations automatically
### 4. Multi-Audience Testing
**Setup:** Duplicate row for each audience
**Change:** Ad Set Name, Targeting fields (Age, Interests, Locations)
**Keep Same:** Campaign Name, Ad creative
### 5. Carousel Product Showcase
**Setup:** Fill Carousel Card 1-10 fields
**Each Card:** Unique product image, title, description, link
**Best For:** E-commerce, feature comparisons
### 6. International Campaign (Multi-Language)
**Setup:** Fill Language 1-5 fields
**Each Language:** Translated copy + localized landing page
**Target:** Multiple countries in ad set targeting
---
## Pro Tips
1. **Naming Conventions**
- Use consistent naming: `[Objective]_[Audience]_[Creative]_v[#]`
- Example: `Traffic_TechEnthusiasts_HeroVideo_v1`
2. **UTM Tracking**
- Always fill UTM fields for proper attribution
- Use UTM Content to identify ad variations
3. **Bulk Variations**
- Duplicate rows to test multiple:
- Audiences (change targeting)
- Creatives (change image/copy)
- Bids (change bid amount)
- Budgets (change daily budget)
4. **File Management**
- Name files systematically: `ProductName_Placement_Version.jpg`
- Example: `OpenClaw_Feed_v1.jpg`, `OpenClaw_Story_v1.jpg`
5. **Testing Strategy**
- Start with 3-5 ad variations per ad set
- Test one variable at a time (audience OR creative, not both)
- Give each ad set 3-5 days before evaluating
6. **Common Mistakes to Avoid**
- Don't use $ symbols in budget fields
- Don't include spaces in file names
- Don't leave required fields blank
- Don't mix Image Hash and Image File (use one or the other)
- Don't forget UTM tracking
---
## Field Count Summary
- **Campaign Fields:** 8
- **Ad Set Fields:** 27
- **Ad Fields:** 30
- **Carousel Fields:** 40 (10 cards × 4 fields)
- **Multi-Language Fields:** 20 (5 languages × 4 fields)
- **Partnership Fields:** 2
**Total Available Fields:** 127+
**Typical Row Uses:** 40-60 fields for standard campaigns
---
Generated by: Buba
Date: 2026-02-11
For: Advertising Report Card
Reference in New Issue View Git Blame Copy Permalink