Google Ads - Ads

📖 Overview

The Ads module manages individual ads within ad groups, including listing, fetching details, and retrieving performance metrics. Supports multiple ad types including responsive search ads, expanded text ads, and display ads.

Source Files:

• Controller: external/Integrations/GoogleAds/Controllers/Ads/AdsController.js
• Model: external/Integrations/GoogleAds/Models/Ads/AdsModel.js
• Routes: external/Integrations/GoogleAds/Routes/ads.js

🔧 API Endpoints

GET /ads - List Ads

Parameters:

Parameter	Type	Required	Description
clientID	String	✅	Client customer ID
managerID	String	✅	Manager customer ID
campaignID	String	❌	Comma-separated campaign IDs
adGroupID	String	❌	Comma-separated ad group IDs
adID	String	❌	Comma-separated ad IDs
campaignType	Enum	❌	Campaign type filter
fromDate	String	❌	Start date (YYYY-MM-DD)
endDate	String	❌	End date (YYYY-MM-DD)
searchText	String	❌	Search by headline/description

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    ads: [
      {
        id: "789456123",
        ad_group_id: "456789123",
        ad_group_name: "Summer Shoes",
        campaign_id: "123456789",
        campaign_name: "Summer Sale",
        status: "ENABLED",
        type: "RESPONSIVE_SEARCH_AD",
        responsive_search_ad: {
          headlines: [
            { text: "Buy Summer Shoes", pinned_field: "HEADLINE_1" },
            { text: "50% Off Sale", pinned_field: null },
            { text: "Free Shipping" }
          ],
          descriptions: [
            { text: "Shop now and save big on summer styles" },
            { text: "Limited time offer. Free returns." }
          ],
          path1: "shoes",
          path2: "sale"
        },
        final_urls: ["https://example.com/summer-shoes"],
        final_mobile_urls: ["https://m.example.com/summer-shoes"]
      }
    ],
    total_results: 120
  }
}

GET /ads/show - Get Single Ad

Parameters:

• clientID, managerID, adID (all required)

Response: Single ad object with full creative details

GET /ads/metrics - Ad Performance Metrics

Parameters: Same as /ads (date range recommended)

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    ads: [
      {
        id: "789456123",
        ad_group_name: "Summer Shoes",
        campaign_name: "Summer Sale",
        type: "RESPONSIVE_SEARCH_AD",
        status: "ENABLED",
        metrics: {
          impressions: 12000,
          clicks: 600,
          ctr: 0.05,
          cost_micros: 4500000, // $4.50
          average_cpc: 7500, // $0.0075
          conversions: 12,
          conversion_rate: 0.02,
          cost_per_conversion: 375000 // $0.375
        },
        ad_strength: "EXCELLENT"
      }
    ]
  }
}

🔧 Ad Types

Supported Ad Types:

• RESPONSIVE_SEARCH_AD - Responsive search ads (RSA)
• EXPANDED_TEXT_AD - Expanded text ads (deprecated by Google)
• TEXT_AD - Standard text ads
• IMAGE_AD - Display image ads
• VIDEO_AD - Video ads (YouTube)
• RESPONSIVE_DISPLAY_AD - Responsive display ads
• SHOPPING_SMART_AD - Smart Shopping ads
• SHOPPING_PRODUCT_AD - Shopping product ads
• APP_AD - App promotion ads
• CALL_ONLY_AD - Call-only ads

🔧 Business Logic

GAQL Query Structure:

SELECT
  ad_group_ad.ad.id,
  ad_group_ad.ad.type,
  ad_group_ad.ad.responsive_search_ad.headlines,
  ad_group_ad.ad.responsive_search_ad.descriptions,
  ad_group_ad.ad.final_urls,
  ad_group_ad.status,
  ad_group.name,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM ad_group_ad
WHERE ad_group.campaign IN (${campaignIDs})
  AND segments.date BETWEEN '${fromDate}' AND '${endDate}'

Ad Status:

• ENABLED - Active and serving
• PAUSED - Paused
• REMOVED - Deleted

Ad Strength (for RSA):

• EXCELLENT - High quality score
• GOOD - Good quality
• AVERAGE - Average quality
• POOR - Needs improvement
• UNSPECIFIED - Not calculated

📝 Responsive Search Ad Structure

Headlines:

• Up to 15 headlines
• Each max 30 characters
• At least 3 required
• Optional pinning to specific positions

Descriptions:

• Up to 4 descriptions
• Each max 90 characters
• At least 2 required

Display Paths:

• path1 and path2 (optional)
• Shown in green text in ad
• Each max 15 characters

Example:

Ad Display:
https://example.com › shoes › sale
Buy Summer Shoes | 50% Off Sale | Free Shipping
Shop now and save big on summer styles. Limited time offer.

⚠️ Important Notes

• 🔐 Hierarchy: Campaign → Ad Group → Ad
• 💡 RSA: Responsive search ads are recommended by Google
• 📊 Ad Strength: Monitor ad strength for RSA performance
• 🎯 Testing: Multiple ads per ad group for A/B testing
• 🔗 Final URLs: Mobile URLs optional but recommended
• 📝 Character Limits: Strict character limits enforced
• 🚨 Deprecated: Expanded text ads no longer supported by Google

🔗 Related Documentation

• Campaigns
• Ad Groups
• Keywords
• Google Ads Ad Docs