Google Ads - Campaigns

📖 Overview

The Campaigns module provides comprehensive campaign management capabilities including listing campaigns, fetching individual campaign details, retrieving performance metrics, and analytics. Supports filtering by campaign type, date ranges, search text, pagination, and sorting.

Source Files:

• Controller: external/Integrations/GoogleAds/Controllers/Campaigns/CampaignController.js
• Model: external/Integrations/GoogleAds/Models/Campaigns/CampaignModel.js
• Routes: external/Integrations/GoogleAds/Routes/campaigns.js

External API: Google Ads API Campaign Service

🗄️ Collections Used

google-ads-token

• Operations: Read
• Model: external/Integrations/GoogleAds/Models/token.js
• Usage Context: Fetch OAuth tokens for API authentication

🔄 Data Flow

Campaign Listing Flow

sequenceDiagram
    participant Client
    participant Controller
    participant Model
    participant GoogleAdsAPI

    Client->>Controller: GET /campaigns?clientID&managerID
    Controller->>Controller: Validate required params
    Controller->>Model: getCampaigns(filters)
    Model->>Model: Build GAQL query
    Model->>GoogleAdsAPI: Execute query
    GoogleAdsAPI-->>Model: Campaign data
    Model->>Model: Format response
    Model-->>Controller: Campaign list
    Controller-->>Client: JSON response

🔧 API Endpoints

GET /campaigns - List Campaigns

Purpose: Retrieve all campaigns for a client account with optional filtering

Parameters:

Parameter	Type	Required	Description
clientID	String	✅	Client customer ID (without hyphens)
managerID	String	✅	Manager customer ID (without hyphens)
campaignID	String	❌	Comma-separated campaign IDs to filter
campaignType	Enum	❌	SEARCH, DISPLAY, SHOPPING, MULTI_CHANNEL, VIDEO
fromDate	String	❌	Start date (YYYY-MM-DD)
endDate	String	❌	End date (YYYY-MM-DD)
date	String	❌	Single date (YYYY-MM-DD)
searchText	String	❌	Search by campaign name
sortField	String	❌	Field to sort by
sortOrder	String	❌	ASC or DESC
pageSize	Number	❌	Results per page
pageToken	String	❌	Pagination token
status	String	❌	Campaign status filter

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    campaigns: [
      {
        id: "123456789",
        name: "Summer Sale Campaign",
        status: "ENABLED",
        campaign_type: "SEARCH",
        advertising_channel_type: "SEARCH",
        advertising_channel_sub_type: null,
        bidding_strategy_type: "TARGET_CPA",
        budget: {
          id: "987654321",
          name: "Summer Budget",
          amount_micros: 50000000, // $50.00
          total_amount_micros: 50000000
        },
        start_date: "2024-06-01",
        end_date: "2024-08-31",
        serving_status: "SERVING",
        target_cpa: {
          target_cpa_micros: 10000000 // $10.00
        }
      }
    ],
    total_results: 15,
    page_token: "next_page_token_here"
  }
}

Example Usage:

// List all campaigns
GET /v1/e/google/ads/campaigns
  ?clientID=1234567890
  &managerID=9876543210

// Filter by campaign type and date range
GET /v1/e/google/ads/campaigns
  ?clientID=1234567890
  &managerID=9876543210
  &campaignType=SEARCH
  &fromDate=2024-01-01
  &endDate=2024-01-31

// Search and paginate
GET /v1/e/google/ads/campaigns
  ?clientID=1234567890
  &managerID=9876543210
  &searchText=summer
  &pageSize=10
  &pageToken=abc123

---

GET /campaigns/show - Get Single Campaign

Purpose: Retrieve detailed information for a specific campaign

Parameters:

• clientID (String, Required)
• managerID (String, Required)
• campaignID (String, Required) - Single campaign ID

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    id: "123456789",
    name: "Summer Sale Campaign",
    status: "ENABLED",
    campaign_type: "SEARCH",
    // ... full campaign details
  }
}

Example Usage:

GET /v1/e/google/ads/campaigns/show
  ?clientID=1234567890
  &managerID=9876543210
  &campaignID=123456789

---

GET /campaigns/metrics - Campaign Metrics

Purpose: Retrieve performance metrics for campaigns

Parameters: Same as /campaigns endpoint

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    campaigns: [
      {
        id: "123456789",
        name: "Summer Sale Campaign",
        status: "ENABLED",
        metrics: {
          impressions: 150000,
          clicks: 7500,
          ctr: 0.05, // 5%
          cost_micros: 45000000, // $45.00
          average_cpc: 6000, // $0.006
          conversions: 150,
          conversion_rate: 0.02, // 2%
          cost_per_conversion: 300000, // $0.30
          impressions_share: 0.75, // 75%
          search_impression_share: 0.72,
          search_rank_lost_impression_share: 0.15
        },
        budget: {
          amount_micros: 50000000,
          spent_micros: 45000000
        }
      }
    ],
    date_range: {
      start_date: "2024-01-01",
      end_date: "2024-01-31"
    },
    total_results: 15
  }
}

Example Usage:

// Get metrics for all campaigns in date range
GET /v1/e/google/ads/campaigns/metrics
  ?clientID=1234567890
  &managerID=9876543210
  &fromDate=2024-01-01
  &endDate=2024-01-31

// Get metrics for specific campaigns
GET /v1/e/google/ads/campaigns/metrics
  ?clientID=1234567890
  &managerID=9876543210
  &campaignID=123456789,987654321

---

🔧 Business Logic & Functions

index() - List Campaigns

Purpose: Retrieve filtered list of campaigns

Business Logic Flow:

1. Validate Required Parameters

   if (!clientID || !managerID) {
     throw new Error('Please provide user clientID and managerID');
   }

2. Normalize Date Parameters

   // Remove time component from dates
   if (fromDate) {
     fromDate = fromDate.split('T')[0]; // "2024-01-01T00:00:00" → "2024-01-01"
   }

3. Build GAQL Query

   let query = `
     SELECT
       campaign.id,
       campaign.name,
       campaign.status,
       campaign.advertising_channel_type,
       campaign.advertising_channel_sub_type,
       campaign.bidding_strategy_type,
       campaign.start_date,
       campaign.end_date,
       campaign_budget.amount_micros
     FROM campaign
     WHERE 1=1
   `;
   
   // Add filters
   if (campaignID) {
     const ids = campaignID.split(',').map(id => id.trim());
     query += ` AND campaign.id IN (${ids.join(',')})`;
   }
   
   if (campaignType) {
     query += ` AND campaign.advertising_channel_type = '${campaignType}'`;
   }
   
   if (searchText) {
     query += ` AND campaign.name LIKE '%${searchText}%'`;
   }
   
   if (status) {
     query += ` AND campaign.status = '${status}'`;
   }
   
   // Add date filters
   if (date) {
     query += ` AND segments.date = '${date}'`;
   } else if (fromDate && endDate) {
     query += ` AND segments.date BETWEEN '${fromDate}' AND '${endDate}'`;
   }
   
   // Add sorting
   if (sortField) {
     query += ` ORDER BY ${sortField} ${sortOrder || 'ASC'}`;
   }
   
   // Add pagination
   if (pageSize) {
     query += ` LIMIT ${pageSize}`;
   }

4. Execute Query

   const response = await googleAdsClient.query(clientID, query, {
     login_customer_id: managerID,
     page_token: pageToken,
   });

5. Format Response

   const campaigns = response.results.map(row => ({
     id: row.campaign.id,
     name: row.campaign.name,
     status: row.campaign.status,
     campaign_type: row.campaign.advertising_channel_type,
     // ... format all fields
   }));
   
   return {
     campaigns,
     total_results: response.total_results_count,
     page_token: response.next_page_token,
   };

Error Handling:

• 400 Missing Parameters: clientID and managerID required
• 400 Invalid Campaign Type: Must be valid enum value
• 400 Invalid Date Format: Must be YYYY-MM-DD
• 403 Access Denied: No access to client account
• 404 Not Found: Campaign ID doesn't exist

---

metrics() - Campaign Metrics

Purpose: Retrieve performance metrics for campaigns

Business Logic Flow:

Similar to index() but includes metrics fields:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.average_cpc,
  metrics.conversions,
  metrics.conversion_rate,
  metrics.cost_per_conversion,
  metrics.impressions_share,
  metrics.search_impression_share
FROM campaign
WHERE segments.date BETWEEN '${fromDate}' AND '${endDate}'

Metrics Calculation:

• CTR: clicks / impressions
• Average CPC: cost_micros / clicks
• Conversion Rate: conversions / clicks
• Cost Per Conversion: cost_micros / conversions

Date Range Requirement:

• Metrics require date range (fromDate and endDate) or single date
• Without dates, returns current day metrics only

---

🔀 Campaign Types

Supported Types:

• UNKNOWN - Unknown type
• SEARCH - Search Network campaigns
• DISPLAY - Display Network campaigns
• SHOPPING - Shopping campaigns
• HOTEL - Hotel campaigns
• VIDEO - Video campaigns (YouTube)
• MULTI_CHANNEL - Multi-channel campaigns
• LOCAL - Local campaigns
• SMART - Smart campaigns
• PERFORMANCE_MAX - Performance Max campaigns

---

🔀 Campaign Status Values

Possible Status:

• ENABLED - Campaign is active
• PAUSED - Campaign is paused
• REMOVED - Campaign is removed
• UNKNOWN - Status unknown
• UNSPECIFIED - Status not specified

Serving Status:

• SERVING - Currently serving ads
• NONE - Not serving
• ENDED - Campaign ended
• PENDING - Pending approval
• SUSPENDED - Suspended by system

---

⚠️ Important Notes

• 🔐 Authentication: Requires valid OAuth token
• 💰 Costs: Cost values in micros (divide by 1,000,000 for dollars)
• ⏱️ Date Format: Always YYYY-MM-DD (no time component)
• 🔄 Pagination: Use pageToken for large result sets
• 📝 GAQL: Uses Google Ads Query Language
• 🚨 Required Headers: login-customer-id must be manager ID
• 🔗 Campaign IDs: Can be comma-separated for multiple campaigns
• 🎯 Metrics Date: Metrics require date range parameter

---

🔗 Related Documentation

• Integration Overview: Google Ads Integration
• Authentication: OAuth Flow
• MCC Operations: Manager Accounts
• Ad Groups: Ad Group Management
• Google Ads Campaign Docs: Campaign Management