Paid Ads

You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.

Before Starting

Check for product marketing context first: If .claude/product-marketing-context.md exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

1. Campaign Goals

• What's the primary objective? (Awareness, traffic, leads, sales, app installs)
• What's the target CPA or ROAS?
• What's the monthly/weekly budget?
• Any constraints? (Brand guidelines, compliance, geographic)

2. Product & Offer

• What are you promoting? (Product, free trial, lead magnet, demo)
• What's the landing page URL?
• What makes this offer compelling?

3. Audience

• Who is the ideal customer?
• What problem does your product solve for them?
• What are they searching for or interested in?
• Do you have existing customer data for lookalikes?

4. Current State

• Have you run ads before? What worked/didn't?
• Do you have existing pixel/conversion data?
• What's your current funnel conversion rate?

---

Platform Selection Guide

---

Campaign Structure Best Practices

Account Organization

Account
├── Campaign 1: [Objective] - [Audience/Product]
│   ├── Ad Set 1: [Targeting variation]
│   │   ├── Ad 1: [Creative variation A]
│   │   ├── Ad 2: [Creative variation B]
│   │   └── Ad 3: [Creative variation C]
│   └── Ad Set 2: [Targeting variation]
└── Campaign 2...

Naming Conventions

[Platform]_[Objective]_[Audience]_[Offer]_[Date]

Examples:
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
GOOG_Search_Brand_Demo_Ongoing
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24

Budget Allocation

Testing phase (first 2-4 weeks):

• 70% to proven/safe campaigns
• 30% to testing new audiences/creative

Scaling phase:

• Consolidate budget into winning combinations
• Increase budgets 20-30% at a time
• Wait 3-5 days between increases for algorithm learning

---

Ad Copy Frameworks

Key Formulas

Problem-Agitate-Solve (PAS):

[Problem] → [Agitate the pain] → [Introduce solution] → [CTA]

Before-After-Bridge (BAB):

[Current painful state] → [Desired future state] → [Your product as bridge]

Social Proof Lead:

[Impressive stat or testimonial] → [What you do] → [CTA]

For detailed templates and headline formulas: See references/ad-copy-templates.md

---

Audience Targeting Overview

Platform Strengths

Key Concepts

• Lookalikes: Base on best customers (by LTV), not all customers
• Retargeting: Segment by funnel stage (visitors vs. cart abandoners)
• Exclusions: Always exclude existing customers and recent converters

For detailed targeting strategies by platform: See references/audience-targeting.md

---

Creative Best Practices

Image Ads

• Clear product screenshots showing UI
• Before/after comparisons
• Stats and numbers as focal point
• Human faces (real, not stock)
• Bold, readable text overlay (keep under 20%)

Video Ads Structure (15-30 sec)

1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
2. Problem (3-8 sec): Relatable pain point
3. Solution (8-20 sec): Show product/benefit
4. CTA (20-30 sec): Clear next step

Production tips:

• Captions always (85% watch without sound)
• Vertical for Stories/Reels, square for feed
• Native feel outperforms polished
• First 3 seconds determine if they watch

Creative Testing Hierarchy

1. Concept/angle (biggest impact)
2. Hook/headline
3. Visual style
4. Body copy
5. CTA

---

Campaign Optimization

Key Metrics by Objective

Optimization Levers

If CPA is too high:

1. Check landing page (is the problem post-click?)
2. Tighten audience targeting
3. Test new creative angles
4. Improve ad relevance/quality score
5. Adjust bid strategy

If CTR is low:

• Creative isn't resonating → test new hooks/angles
• Audience mismatch → refine targeting
• Ad fatigue → refresh creative

If CPM is high:

• Audience too narrow → expand targeting
• High competition → try different placements
• Low relevance score → improve creative fit

Bid Strategy Progression

1. Start with manual or cost caps
2. Gather conversion data (50+ conversions)
3. Switch to automated with targets based on historical data
4. Monitor and adjust targets based on results

---

Retargeting Strategies

Funnel-Based Approach

Retargeting Windows

Exclusions to Set Up

• Existing customers (unless upsell)
• Recent converters (7-14 day window)
• Bounced visitors (<10 sec)
• Irrelevant pages (careers, support)

---

Reporting & Analysis

Weekly Review

• Spend vs. budget pacing
• CPA/ROAS vs. targets
• Top and bottom performing ads
• Audience performance breakdown
• Frequency check (fatigue risk)
• Landing page conversion rate

Attribution Considerations

• Platform attribution is inflated
• Use UTM parameters consistently
• Compare platform data to GA4
• Look at blended CAC, not just platform CPA

---

Platform Setup

Before launching campaigns, ensure proper tracking and account setup.

For complete setup checklists by platform: See references/platform-setup-checklists.md

Universal Pre-Launch Checklist

• Conversion tracking tested with real conversion
• Landing page loads fast (<3 sec)
• Landing page mobile-friendly
• UTM parameters working
• Budget set correctly
• Targeting matches intended audience

---

Common Mistakes to Avoid

Strategy

• Launching without conversion tracking
• Too many campaigns (fragmenting budget)
• Not giving algorithms enough learning time
• Optimizing for wrong metric

Targeting

• Audiences too narrow or too broad
• Not excluding existing customers
• Overlapping audiences competing

Creative

• Only one ad per ad set
• Not refreshing creative (fatigue)
• Mismatch between ad and landing page

Budget

• Spreading too thin across campaigns
• Making big budget changes (disrupts learning)
• Stopping campaigns during learning phase

---

Task-Specific Questions

1. What platform(s) are you currently running or want to start with?
2. What's your monthly ad budget?
3. What does a successful conversion look like (and what's it worth)?
4. Do you have existing creative assets or need to create them?
5. What landing page will ads point to?
6. Do you have pixel/conversion tracking set up?

---

Tool Integrations

For implementation, see the tools registry (../../tools/REGISTRY.md). Key advertising platforms:

For tracking, see also: ga4.md (../../tools/integrations/ga4.md), segment.md (../../tools/integrations/segment.md)

---

Related Skills

• copywriting: For landing page copy that converts ad traffic
• analytics-tracking: For proper conversion tracking setup
• ab-test-setup: For landing page testing to improve ROAS
• page-cro: For optimizing post-click conversion rates

---

Supporting file: references/ad-copy-templates.md

Ad Copy Templates Reference

Detailed formulas and templates for writing high-converting ad copy.

Primary Text Formulas

Problem-Agitate-Solve (PAS)

[Problem statement]
[Agitate the pain]
[Introduce solution]
[CTA]

Example:

Spending hours on manual reporting every week? While you're buried in spreadsheets, your competitors are making decisions. [Product] automates your reports in minutes. Start your free trial →

---

Before-After-Bridge (BAB)

[Current painful state]
[Desired future state]
[Your product as the bridge]

Example:

Before: Chasing down approvals across email, Slack, and spreadsheets. After: Every approval tracked, automated, and on time. [Product] connects your tools and keeps projects moving.

---

Social Proof Lead

[Impressive stat or testimonial]
[What you do]
[CTA]

Example:

"We cut our reporting time by 75%." — Sarah K., Marketing Director [Product] automates the reports you hate building. See how it works →

---

Feature-Benefit Bridge

[Feature]
[So that...]
[Which means...]

Example:

Real-time collaboration on documents So your team always works from the latest version Which means no more version confusion or lost work

---

Direct Response

[Bold claim/outcome]
[Proof point]
[CTA with urgency if genuine]

Example:

Cut your reporting time by 80% Join 5,000+ marketing teams already using [Product] Start free → First month 50% off

---

Headline Formulas

For Search Ads

For Social Ads

---

CTA Variations

Soft CTAs (awareness/consideration)

Best for: Top of funnel, cold audiences, complex products

• Learn More
• See How It Works
• Watch Demo
• Get the Guide
• Explore Features
• See Examples
• Read the Case Study

Hard CTAs (conversion)

Best for: Bottom of funnel, warm audiences, clear offers

• Start Free Trial
• Get Started Free
• Book a Demo
• Claim Your Discount
• Buy Now
• Sign Up Free
• Get Instant Access

Urgency CTAs (use when genuine)

Best for: Limited-time offers, scarcity situations

• Limited Time: 30% Off
• Offer Ends [Date]
• Only X Spots Left
• Last Chance
• Early Bird Pricing Ends Soon

Action-Oriented CTAs

Best for: Active voice, clear next step

• Start Saving Time Today
• Get Your Free Report
• See Your Score
• Calculate Your ROI
• Build Your First Project

---

Platform-Specific Copy Guidelines

Google Search Ads

• Headline limits: 30 characters each (up to 15 headlines)
• Description limits: 90 characters each (up to 4 descriptions)
• Include keywords naturally
• Use all available headline slots
• Include numbers and stats when possible
• Test dynamic keyword insertion

Meta Ads (Facebook/Instagram)

• Primary text: 125 characters visible (can be longer, gets truncated)
• Headline: 40 characters recommended
• Front-load the hook (first line matters most)
• Emojis can work but test
• Questions perform well
• Keep image text under 20%

LinkedIn Ads

• Intro text: 600 characters max (150 recommended)
• Headline: 200 characters max (70 recommended)
• Professional tone (but not boring)
• Specific job outcomes resonate
• Stats and social proof important
• Avoid consumer-style hype

---

Copy Testing Priority

When testing ad copy, focus on these elements in order of impact:

1. Hook/angle (biggest impact on performance)
2. Headline
3. Primary benefit
4. CTA
5. Supporting proof points

Test one element at a time for clean data.

---

Supporting file: references/audience-targeting.md

Audience Targeting Reference

Detailed targeting strategies for each major ad platform.

Google Ads Audiences

Search Campaign Targeting

Keywords:

• Exact match: [keyword] — most precise, lower volume
• Phrase match: "keyword" — moderate precision and volume
• Broad match: keyword — highest volume, use with smart bidding

Audience layering:

• Add audiences in "observation" mode first
• Analyze performance by audience
• Switch to "targeting" mode for high performers

RLSA (Remarketing Lists for Search Ads):

• Bid higher on past visitors searching your terms
• Show different ads to returning searchers
• Exclude converters from prospecting campaigns

Display/YouTube Targeting

Custom intent audiences:

• Based on recent search behavior
• Create from your converting keywords
• High intent, good for prospecting

In-market audiences:

• People actively researching solutions
• Pre-built by Google
• Layer with demographics for precision

Affinity audiences:

• Based on interests and habits
• Better for awareness
• Broad but can exclude irrelevant

Customer match:

• Upload email lists
• Retarget existing customers
• Create lookalikes from best customers

Similar/lookalike audiences:

• Based on your customer match lists
• Expand reach while maintaining relevance
• Best when source list is high-quality customers

---

Meta Audiences

Core Audiences (Interest/Demographic)

Interest targeting tips:

• Layer interests with AND logic for precision
• Use Audience Insights to research interests
• Start broad, let algorithm optimize
• Exclude existing customers always

Demographic targeting:

• Age and gender (if product-specific)
• Location (down to zip/postal code)
• Language
• Education and work (limited data now)

Behavior targeting:

• Purchase behavior
• Device usage
• Travel patterns
• Life events

Custom Audiences

Website visitors:

• All visitors (last 180 days max)
• Specific page visitors
• Time on site thresholds
• Frequency (visited X times)

Customer list:

• Upload emails/phone numbers
• Match rate typically 30-70%
• Refresh regularly for accuracy

Engagement audiences:

• Video viewers (25%, 50%, 75%, 95%)
• Page/profile engagers
• Form openers
• Instagram engagers

App activity:

• App installers
• In-app events
• Purchase events

Lookalike Audiences

Source audience quality matters:

• Use high-LTV customers, not all customers
• Purchasers > leads > all visitors
• Minimum 100 source users, ideally 1,000+

Size recommendations:

• 1% — most similar, smallest reach
• 1-3% — good balance for most
• 3-5% — broader, good for scale
• 5-10% — very broad, awareness only

Layering strategies:

• Lookalike + interest = more precision early
• Test lookalike-only as you scale
• Exclude the source audience

---

LinkedIn Audiences

Job-Based Targeting

Job titles:

• Be specific (CMO vs. "Marketing")
• LinkedIn normalizes titles, but verify
• Stack related titles
• Exclude irrelevant titles

Job functions:

• Broader than titles
• Combine with seniority level
• Good for awareness campaigns

Seniority levels:

• Entry, Senior, Manager, Director, VP, CXO, Partner
• Layer with function for precision

Skills:

• Self-reported, less reliable
• Good for technical roles
• Use as expansion layer

Company-Based Targeting

Company size:

• 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+
• Key filter for B2B

Industry:

• Based on company classification
• Can be broad, layer with other criteria

Company names (ABM):

• Upload target account list
• Minimum 300 companies recommended
• Match rate varies

Company growth rate:

• Hiring rapidly = budget available
• Good signal for timing

High-Performing Combinations

---

Twitter/X Audiences

Targeting options:

• Follower lookalikes (accounts similar to followers of X)
• Interest categories
• Keywords (in tweets)
• Conversation topics
• Events
• Tailored audiences (your lists)

Best practices:

• Follower lookalikes of relevant accounts work well
• Keyword targeting catches active conversations
• Lower CPMs than LinkedIn/Meta
• Less precise, better for awareness

---

TikTok Audiences

Targeting options:

• Demographics (age, gender, location)
• Interests (TikTok's categories)
• Behaviors (video interactions)
• Device (iOS/Android, connection type)
• Custom audiences (pixel, customer file)
• Lookalike audiences

Best practices:

• Younger skew (18-34 primarily)
• Interest targeting is broad
• Creative matters more than targeting
• Let algorithm optimize with broad targeting

---

Audience Size Guidelines

Too narrow = expensive, slow learning Too broad = wasted spend, poor relevance

---

Exclusion Strategy

Always exclude:

• Existing customers (unless upsell)
• Recent converters (7-14 days)
• Bounced visitors (<10 sec)
• Employees (by company or email list)
• Irrelevant page visitors (careers, support)
• Competitors (if identifiable)

---

Supporting file: references/platform-setup-checklists.md

Platform Setup Checklists

Complete setup checklists for major ad platforms.

Google Ads Setup

Account Foundation

• Google Ads account created and verified
• Billing information added
• Time zone and currency set correctly
• Account access granted to team members

Conversion Tracking

• Google tag installed on all pages
• Conversion actions created (purchase, lead, signup)
• Conversion values assigned (if applicable)
• Enhanced conversions enabled
• Test conversions firing correctly
• Import conversions from GA4 (optional)

Analytics Integration

• Google Analytics 4 linked
• Auto-tagging enabled
• GA4 audiences available in Google Ads
• Cross-domain tracking set up (if multiple domains)

Audience Setup

• Remarketing tag verified
• Website visitor audiences created:
  • All visitors (180 days)
  • Key page visitors (pricing, demo, features)
  • Converters (for exclusion)
• Customer match lists uploaded
• Similar audiences enabled

Campaign Readiness

• Negative keyword lists created:
  • Universal negatives (free, jobs, careers, reviews, complaints)
  • Competitor negatives (if needed)
  • Irrelevant industry terms
• Location targeting set (include/exclude)
• Language targeting set
• Ad schedule configured (if B2B, business hours)
• Device bid adjustments considered

Ad Extensions

• Sitelinks (4-6 relevant pages)
• Callouts (key benefits, offers)
• Structured snippets (features, types, services)
• Call extension (if phone leads valuable)
• Lead form extension (if using)
• Price extensions (if applicable)
• Image extensions (where available)

Brand Protection

• Brand campaign running (protect branded terms)
• Competitor campaigns considered
• Brand terms in negative lists for non-brand campaigns

---

Meta Ads Setup

Business Manager Foundation

• Business Manager created
• Business verified (if running certain ad types)
• Ad account created within Business Manager
• Payment method added
• Team access configured with proper roles

Pixel & Tracking

• Meta Pixel installed on all pages
• Standard events configured:
  • PageView (automatic)
  • ViewContent (product/feature pages)
  • Lead (form submissions)
  • Purchase (conversions)
  • AddToCart (if e-commerce)
  • InitiateCheckout (if e-commerce)
• Conversions API (CAPI) set up for server-side tracking
• Event Match Quality score > 6
• Test events in Events Manager

Domain & Aggregated Events

• Domain verified in Business Manager
• Aggregated Event Measurement configured
• Top 8 events prioritized in order of importance
• Web events prioritized for iOS 14+ tracking

Audience Setup

• Custom audiences created:
  • Website visitors (all, 30/60/90/180 days)
  • Key page visitors
  • Video viewers (25%, 50%, 75%, 95%)
  • Page/Instagram engagers
  • Customer list uploaded
• Lookalike audiences created (1%, 1-3%)
• Saved audiences for common targeting

Catalog (E-commerce)

• Product catalog connected
• Product feed updating correctly
• Catalog sales campaigns enabled
• Dynamic product ads configured

Creative Assets

• Images in correct sizes:
  • Feed: 1080x1080 (1:1)
  • Stories/Reels: 1080x1920 (9:16)
  • Landscape: 1200x628 (1.91:1)
• Videos in correct formats
• Ad copy variations ready
• UTM parameters in all destination URLs

Compliance

• Special Ad Categories declared (if housing, credit, employment, politics)
• Landing page complies with Meta policies
• No prohibited content in ads

---

LinkedIn Ads Setup

Campaign Manager Foundation

• Campaign Manager account created
• Company Page connected
• Billing information added
• Team access configured

Insight Tag & Tracking

• LinkedIn Insight Tag installed on all pages
• Tag verified and firing
• Conversion tracking configured:
  • URL-based conversions
  • Event-specific conversions
• Conversion values set (if applicable)

Audience Setup

• Matched Audiences created:
  • Website retargeting audiences
  • Company list uploaded (for ABM)
  • Contact list uploaded
• Lookalike audiences created
• Saved audiences for common targeting

Lead Gen Forms (if using)

• Lead gen form templates created
• Form fields selected (minimize for conversion)
• Privacy policy URL added
• Thank you message configured
• CRM integration set up (or CSV export process)

Document Ads (if using)

• Documents uploaded (PDF, PowerPoint)
• Gating configured (full gate or preview)
• Lead gen form connected

Creative Assets

• Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1)
• Carousel images ready
• Video specs met (if using)
• Ad copy within character limits:
  • Intro text: 600 max, 150 recommended
  • Headline: 200 max, 70 recommended

Budget Considerations

• Budget realistic for LinkedIn CPCs ($8-15+ typical)
• Audience size validated (50K+ recommended)
• Daily vs. lifetime budget decided
• Bid strategy selected

---

Twitter/X Ads Setup

Account Foundation

• Ads account created
• Payment method added
• Account verified (if required)

Tracking

• Twitter Pixel installed
• Conversion events created
• Website tag verified

Audience Setup

• Tailored audiences created:
  • Website visitors
  • Customer lists
• Follower lookalikes identified
• Interest and keyword targets researched

Creative

• Tweet copy within 280 characters
• Images: 1200x675 (1.91:1) or 1200x1200 (1:1)
• Video specs met (if using)
• Cards configured (website, app, etc.)

---

TikTok Ads Setup

Account Foundation

• TikTok Ads Manager account created
• Business verification completed
• Payment method added

Pixel & Tracking

• TikTok Pixel installed
• Events configured (ViewContent, Purchase, etc.)
• Events API set up (recommended)

Audience Setup

• Custom audiences created
• Lookalike audiences created
• Interest categories identified

Creative

• Vertical video (9:16) ready
• Native-feeling content (not too polished)
• First 3 seconds are compelling hooks
• Captions added (most watch without sound)
• Music/sounds selected (licensed if needed)

---

Universal Pre-Launch Checklist

Before launching any campaign:

• Conversion tracking tested with real conversion
• Landing page loads fast (<3 sec)
• Landing page mobile-friendly
• UTM parameters working
• Budget set correctly (daily vs. lifetime)
• Start/end dates correct
• Targeting matches intended audience
• Ad creative approved
• Team notified of launch
• Reporting dashboard ready

---

Supporting file: tools/REGISTRY.md

Marketing Tools Registry

Quick reference for AI agents to discover tool capabilities and integration methods.

How to Use This Registry

1. Find tools by category - Browse sections below for tools in each domain
2. Check integration methods - See what APIs, MCPs, CLIs, or SDKs are available
3. Read integration guides - Detailed setup and common operations in integrations/

---

Tool Index

---

By Category

Analytics

Track user behavior, measure conversions, and analyze marketing performance.

Agent recommendation: Start with GA4 if using Google ecosystem. Use Mixpanel or Amplitude for deeper product analytics.

SEO

Search engine optimization tools for keyword research, rank tracking, and site audits.

Agent recommendation: Google Search Console is essential (free). Add Semrush or Ahrefs for competitive research.

CRM

Customer relationship management and sales tools.

Agent recommendation: HubSpot for startups/SMBs, Salesforce for enterprise.

Payments

Payment processing and subscription management.

Agent recommendation: Stripe is the default for SaaS and developer-focused products.

Referral & Affiliate

Tools for referral programs, affiliate tracking, and partner management.

Agent recommendation: Rewardful or Tolt for Stripe-based SaaS. Dub.co for link attribution.

Email

Email marketing, transactional email, and automation platforms.

Agent recommendation: Resend for transactional (dev-friendly). Customer.io for advanced automation. Kit for creators.

Advertising

Paid advertising platforms and campaign management.

Agent recommendation: Google Ads for search intent. Meta for demand generation. LinkedIn for B2B.

Automation

Workflow automation and integration platforms.

Agent recommendation: Zapier for connecting tools without code.

Commerce & CMS

E-commerce platforms and content management systems.

Agent recommendation: Shopify for e-commerce. Webflow for marketing sites. WordPress for blogs.

---

MCP-Enabled Tools

These tools have Model Context Protocol servers available, enabling direct agent interaction:

• ga4 - Google Analytics 4 data access
• stripe - Payment and subscription management
• mailchimp - Email campaign management
• google-ads - Ad campaign management
• resend - Transactional email sending
• zapier - Workflow automation

To use MCP tools, ensure the appropriate MCP server is configured in your environment.

---

Quick Start by Use Case

Setting up analytics tracking

1. Read ga4.md (integrations/ga4.md) for web analytics
2. Read segment.md (integrations/segment.md) if routing to multiple tools

Launching a referral program

1. Read rewardful.md (integrations/rewardful.md) or tolt.md (integrations/tolt.md) for Stripe-based programs
2. Read dub-co.md (integrations/dub-co.md) for link tracking

Setting up email automation

1. Read customer-io.md (integrations/customer-io.md) for behavior-based automation
2. Read resend.md (integrations/resend.md) for transactional email

Running paid ads

1. Read google-ads.md (integrations/google-ads.md) for search campaigns
2. Read meta-ads.md (integrations/meta-ads.md) for social campaigns

---

Supporting file: tools/integrations/ga4.md

Google Analytics 4 (GA4)

Web analytics platform for tracking user behavior, conversions, and marketing performance.

Capabilities

Authentication

• Type: OAuth 2.0 or Service Account
• Scopes: https://www.googleapis.com/auth/analytics.readonly (read), https://www.googleapis.com/auth/analytics.edit (write)
• Setup: Create credentials in Google Cloud Console

Common Agent Operations

Run a report (Data API)

POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runReport

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "sessionSource"}],
  "metrics": [{"name": "sessions"}, {"name": "conversions"}]
}

Get real-time data

POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runRealtimeReport

{
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}]
}

List conversion events

GET https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents

Create a conversion event

POST https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents

{
  "eventName": "purchase"
}

Client-Side Tracking

Send custom event (gtag.js)

gtag('event', 'signup_completed', {
  'method': 'email',
  'plan': 'free'
});

Send event via Measurement Protocol

POST https://www.google-analytics.com/mp/collect?measurement_id={measurement_id}&api_secret={api_secret}

{
  "client_id": "client_123",
  "events": [{
    "name": "purchase",
    "params": {
      "value": 99.99,
      "currency": "USD"
    }
  }]
}

Key Dimensions & Metrics

Common Dimensions

• sessionSource - Traffic source
• sessionMedium - Traffic medium
• sessionCampaignName - Campaign name
• landingPage - Entry page
• deviceCategory - Device type
• country - User country

Common Metrics

• sessions - Total sessions
• activeUsers - Active users
• newUsers - New users
• conversions - Conversion events
• engagementRate - Engaged sessions rate
• averageSessionDuration - Session duration

When to Use

• Tracking website traffic and user behavior
• Measuring marketing campaign performance
• Setting up conversion tracking
• Analyzing user journeys and funnels
• Attribution modeling

Rate Limits

• Data API: 10 requests per second per property
• Admin API: Varies by endpoint
• Measurement Protocol: 1M hits/day for free tier

Relevant Skills

• analytics-tracking
• ab-test-setup
• seo-audit
• page-cro

---

Supporting file: tools/integrations/google-ads.md

Google Ads

Pay-per-click advertising platform for search, display, and video campaigns.

Capabilities

Authentication

• Type: OAuth 2.0
• Scopes: https://www.googleapis.com/auth/adwords
• Setup: Create credentials in Google Cloud Console, link to Google Ads account
• Headers: developer-token, login-customer-id (for MCC)

Common Agent Operations

Get account info

POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream

{
  "query": "SELECT customer.id, customer.descriptive_name FROM customer"
}

List campaigns

POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream

{
  "query": "SELECT campaign.id, campaign.name, campaign.status, campaign_budget.amount_micros FROM campaign ORDER BY campaign.id"
}

Get campaign performance

POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream

{
  "query": "SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS"
}

Get ad group performance

POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream

{
  "query": "SELECT ad_group.name, metrics.impressions, metrics.clicks, metrics.conversions FROM ad_group WHERE segments.date DURING LAST_7_DAYS"
}

Get keyword performance

POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream

{
  "query": "SELECT ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks, metrics.average_cpc FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 50"
}

Pause campaign

POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaigns:mutate

{
  "operations": [{
    "update": {
      "resourceName": "customers/{customer_id}/campaigns/{campaign_id}",
      "status": "PAUSED"
    },
    "updateMask": "status"
  }]
}

Update budget

POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaignBudgets:mutate

{
  "operations": [{
    "update": {
      "resourceName": "customers/{customer_id}/campaignBudgets/{budget_id}",
      "amountMicros": "50000000"
    },
    "updateMask": "amountMicros"
  }]
}

Key Metrics

Campaign Types

• SEARCH - Search network text ads
• DISPLAY - Display network
• SHOPPING - Product shopping ads
• VIDEO - YouTube video ads
• PERFORMANCE_MAX - AI-optimized across channels
• DEMAND_GEN - Discovery/Demand Gen

GAQL (Google Ads Query Language)

SELECT
  campaign.name,
  metrics.clicks,
  metrics.conversions
FROM campaign
WHERE
  campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.conversions DESC
LIMIT 10

When to Use

• Managing search advertising campaigns
• Analyzing campaign performance
• Adjusting budgets and bids
• Keyword research and management
• Conversion tracking analysis

Rate Limits

• 15,000 operations per day (basic)
• Higher limits with developer token levels

Relevant Skills

• paid-ads
• analytics-tracking
• page-cro

---

Supporting file: tools/integrations/linkedin-ads.md

LinkedIn Ads

B2B advertising platform with professional targeting.

Capabilities

Authentication

• Type: OAuth 2.0
• Header: Authorization: Bearer {access_token}
• Scopes: r_ads, r_ads_reporting, rw_ads

Common Agent Operations

Get ad accounts

GET https://api.linkedin.com/v2/adAccountsV2?q=search

Authorization: Bearer {access_token}

Get campaigns

GET https://api.linkedin.com/v2/adCampaignsV2?q=search&search.account.values[0]=urn:li:sponsoredAccount:{account_id}

Authorization: Bearer {access_token}

Get campaign analytics

GET https://api.linkedin.com/v2/adAnalyticsV2?q=analytics&pivot=CAMPAIGN&dateRange.start.year=2024&dateRange.start.month=1&dateRange.start.day=1&dateRange.end.year=2024&dateRange.end.month=1&dateRange.end.day=31&campaigns=urn:li:sponsoredCampaign:{campaign_id}&fields=impressions,clicks,costInLocalCurrency,conversions

Authorization: Bearer {access_token}

Create campaign

POST https://api.linkedin.com/v2/adCampaignsV2

Authorization: Bearer {access_token}

{
  "account": "urn:li:sponsoredAccount:{account_id}",
  "name": "Campaign Name",
  "type": "SPONSORED_UPDATES",
  "costType": "CPC",
  "unitCost": {
    "amount": "5.00",
    "currencyCode": "USD"
  },
  "dailyBudget": {
    "amount": "100.00",
    "currencyCode": "USD"
  },
  "status": "PAUSED"
}

Update campaign status

POST https://api.linkedin.com/v2/adCampaignsV2/{campaign_id}

Authorization: Bearer {access_token}

{
  "patch": {
    "$set": {
      "status": "ACTIVE"
    }
  }
}

Get creatives

GET https://api.linkedin.com/v2/adCreativesV2?q=search&search.campaign.values[0]=urn:li:sponsoredCampaign:{campaign_id}

Authorization: Bearer {access_token}

Get audience counts

POST https://api.linkedin.com/v2/audienceCountsV2

{
  "audienceCriteria": {
    "include": {
      "and": [{
        "or": {
          "urn:li:adTargetingFacet:titles": ["urn:li:title:123"]
        }
      }]
    }
  }
}

Key Metrics

Campaign Types

• SPONSORED_UPDATES - Sponsored content
• TEXT_AD - Text ads
• SPONSORED_INMAILS - Message ads
• DYNAMIC - Dynamic ads

Targeting Options

Job-Based

• Job titles
• Job functions
• Seniority levels
• Years of experience

Company-Based

• Company names
• Industries
• Company size
• Company followers

Professional

• Skills
• Groups
• Schools
• Degrees

When to Use

• B2B advertising
• Job title targeting
• Account-based marketing
• Lead generation campaigns

Rate Limits

• 100 requests/day (basic)
• 10,000 requests/day (Marketing Developer Platform)

Relevant Skills

• paid-ads
• analytics-tracking

---

Supporting file: tools/integrations/meta-ads.md

Meta Ads (Facebook/Instagram)

Advertising platform for Facebook, Instagram, Messenger, and Audience Network.

Capabilities

Authentication

• Type: OAuth 2.0 Access Token
• Header: Access token as query parameter
• Setup: Create app in Meta Business Suite, generate System User token

Common Agent Operations

Get ad accounts

GET https://graph.facebook.com/v18.0/me/adaccounts?access_token={access_token}&fields=id,name,account_status

Get campaigns

GET https://graph.facebook.com/v18.0/act_{ad_account_id}/campaigns?access_token={access_token}&fields=id,name,status,objective,daily_budget

Get campaign insights

GET https://graph.facebook.com/v18.0/{campaign_id}/insights?access_token={access_token}&fields=impressions,clicks,spend,actions,cost_per_action_type&date_preset=last_30d

Get ad sets

GET https://graph.facebook.com/v18.0/act_{ad_account_id}/adsets?access_token={access_token}&fields=id,name,status,targeting,daily_budget,bid_amount

Get ads

GET https://graph.facebook.com/v18.0/{ad_set_id}/ads?access_token={access_token}&fields=id,name,status,creative

Create campaign

POST https://graph.facebook.com/v18.0/act_{ad_account_id}/campaigns

access_token={access_token}
&name=Campaign Name
&objective=CONVERSIONS
&status=PAUSED
&special_ad_categories=[]

Update campaign status

POST https://graph.facebook.com/v18.0/{campaign_id}

access_token={access_token}
&status=ACTIVE

Get custom audiences

GET https://graph.facebook.com/v18.0/act_{ad_account_id}/customaudiences?access_token={access_token}&fields=id,name,approximate_count

Create lookalike audience

POST https://graph.facebook.com/v18.0/act_{ad_account_id}/customaudiences

access_token={access_token}
&name=Lookalike - Top Customers
&subtype=LOOKALIKE
&origin_audience_id={source_audience_id}
&lookalike_spec={"type":"similarity","country":"US"}

Key Metrics

Campaign Objectives

• AWARENESS - Brand awareness
• TRAFFIC - Website traffic
• ENGAGEMENT - Post engagement
• LEADS - Lead generation
• APP_PROMOTION - App installs
• SALES - Conversions/catalog sales

Targeting Options

{
  "geo_locations": {
    "countries": ["US"],
    "cities": [{"key": "2420379"}]
  },
  "age_min": 25,
  "age_max": 45,
  "genders": [1, 2],
  "interests": [{"id": "6003139266461", "name": "Marketing"}],
  "behaviors": [{"id": "6002714895372"}]
}

When to Use

• Creating/managing Facebook and Instagram ads
• Audience targeting and lookalikes
• Campaign performance analysis
• Retargeting setup

Rate Limits

• 200 calls/hour per ad account
• 60 calls/hour for marketing API
• Use batch requests for efficiency

Relevant Skills

• paid-ads
• analytics-tracking
• page-cro

---

Supporting file: tools/integrations/segment.md

Segment

Customer data platform for collecting, routing, and activating user data.

Capabilities

Authentication

• Tracking: Write Key (per source)
• API: Access Token (OAuth 2.0)
• Header: Authorization: Bearer {access_token}

Common Agent Operations

Track event

POST https://api.segment.io/v1/track

Authorization: Basic {base64(write_key:)}

{
  "userId": "user_123",
  "event": "signup_completed",
  "properties": {
    "plan": "pro",
    "method": "email"
  }
}

Identify user

POST https://api.segment.io/v1/identify

Authorization: Basic {base64(write_key:)}

{
  "userId": "user_123",
  "traits": {
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "pro"
  }
}

Track page view

POST https://api.segment.io/v1/page

Authorization: Basic {base64(write_key:)}

{
  "userId": "user_123",
  "name": "Pricing",
  "properties": {
    "title": "Pricing - Example",
    "url": "https://example.com/pricing"
  }
}

Batch events

POST https://api.segment.io/v1/batch

Authorization: Basic {base64(write_key:)}

{
  "batch": [
    {"type": "identify", "userId": "user_1", "traits": {"plan": "free"}},
    {"type": "track", "userId": "user_1", "event": "signup"}
  ]
}

Get user profile (Profile API)

GET https://profiles.segment.com/v1/spaces/{space_id}/collections/users/profiles/user_id:{user_id}/traits

Authorization: Basic {base64(access_token:)}

Get user events

GET https://profiles.segment.com/v1/spaces/{space_id}/collections/users/profiles/user_id:{user_id}/events

Authorization: Basic {base64(access_token:)}

JavaScript SDK

// Initialize
analytics.load('WRITE_KEY');

// Identify user
analytics.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro'
});

// Track event
analytics.track('Feature Used', {
  feature_name: 'export'
});

// Page view
analytics.page('Pricing');

Key Concepts

• Sources - Where data comes from (website, app, server)
• Destinations - Where data goes (analytics, CRM, ads)
• Tracking Plan - Schema for events and properties
• Protocols - Data governance and validation
• Personas - Unified user profiles
• Audiences - Computed user segments

Common Destinations

• Analytics: GA4, Mixpanel, Amplitude
• CRM: HubSpot, Salesforce
• Email: Customer.io, Mailchimp
• Ads: Google Ads, Meta
• Data Warehouse: BigQuery, Snowflake

When to Use

• Centralizing event tracking
• Routing data to multiple tools
• Maintaining consistent tracking
• Building unified user profiles
• Syncing audiences across platforms

Rate Limits

• 500 requests/second per source
• Batch up to 500KB or 32KB per event

Relevant Skills

• analytics-tracking
• email-sequence
• paid-ads

---

Supporting file: tools/integrations/tiktok-ads.md

TikTok Ads

Advertising platform for TikTok's short-form video audience.

Capabilities

Authentication

• Type: Access Token
• Header: Access-Token: {access_token}
• Setup: Create app in TikTok for Business, get access token

Common Agent Operations

Get advertiser info

GET https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_ids=["{advertiser_id}"]

Access-Token: {access_token}

Get campaigns

GET https://business-api.tiktok.com/open_api/v1.3/campaign/get/?advertiser_id={advertiser_id}&page=1&page_size=20

Access-Token: {access_token}

Get campaign report

POST https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/

Access-Token: {access_token}

{
  "advertiser_id": "{advertiser_id}",
  "report_type": "BASIC",
  "dimensions": ["campaign_id"],
  "metrics": ["spend", "impressions", "clicks", "conversion"],
  "data_level": "AUCTION_CAMPAIGN",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Create campaign

POST https://business-api.tiktok.com/open_api/v1.3/campaign/create/

Access-Token: {access_token}

{
  "advertiser_id": "{advertiser_id}",
  "campaign_name": "Campaign Name",
  "objective_type": "CONVERSIONS",
  "budget_mode": "BUDGET_MODE_DAY",
  "budget": 100
}

Update campaign status

POST https://business-api.tiktok.com/open_api/v1.3/campaign/status/update/

Access-Token: {access_token}

{
  "advertiser_id": "{advertiser_id}",
  "campaign_ids": ["{campaign_id}"],
  "opt_status": "ENABLE"
}

Get ad groups

GET https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={advertiser_id}&campaign_ids=["{campaign_id}"]

Access-Token: {access_token}

Get audiences

GET https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/?advertiser_id={advertiser_id}

Access-Token: {access_token}

Key Metrics

Campaign Objectives

• REACH - Brand awareness
• TRAFFIC - Website traffic
• VIDEO_VIEWS - Video views
• LEAD_GENERATION - Lead forms
• CONVERSIONS - Website conversions
• APP_PROMOTION - App installs

Targeting Options

Demographics

• Age ranges
• Gender
• Languages
• Locations

Interests & Behavior

• Interest categories
• Video interactions
• Creator interactions
• Hashtag interactions

Custom Audiences

• Customer file uploads
• Website visitors (pixel)
• App activity
• Engagement audiences

When to Use

• Reaching younger demographics (18-34)
• Video-first advertising
• Viral/creative campaigns
• App promotion

Rate Limits

• 10 requests/second
• 100,000 requests/day

Relevant Skills

• paid-ads
• analytics-tracking