Google Ads Integration

🎯 Overview

The Google Ads integration provides comprehensive access to Google's advertising platform, enabling campaign management, ad group operations, keyword management, ad creation/editing, and performance analytics. This integration supports MCC (Manager account) operations for managing multiple client accounts.

Provider: Google Ads (https://ads.google.com)
API Version: Latest (configured via environment variables)
Integration Type: OAuth 2.0 + REST API
Client Library: Opteo Google Ads API (third-party Node.js client)

📁 Directory Structure

Documentation Structure:

google-ads/
├── 📄 index.md - Integration overview and setup
├── 📄 authentication.md - OAuth flow and token management
├── 📄 campaigns.md - Campaign operations and metrics
├── 📄 ad-groups.md - Ad group management
├── 📄 ads.md - Ad creation and editing
├── 📄 keywords.md - Keyword management
└── 📄 mcc.md - Manager account operations

Source Code Location:

• Base Path: external/Integrations/GoogleAds/
• Controllers: Controllers/ (modular structure by resource)
  • Auth/AuthController.js
  • Campaigns/CampaignController.js
  • Adgroups/AdGroupController.js
  • Ads/AdsController.js
  • Keywords/KeyWordsController.js
  • Mcc/ - Manager account operations
  • GoogleAdsApi.js - Base API wrapper
• Routes: Routes/ (one per resource)
• Models: Models/ (token, config)
• Utils: Utils/ (enums, helpers)

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

google-ads-token

• Purpose: Store OAuth access and refresh tokens
• Model: external/Integrations/GoogleAds/Models/token.js
• Primary Use: Store Google OAuth tokens, manager/client IDs, token expiration

google-ads-config

• Purpose: Store Google Ads configuration and settings
• Model: external/Integrations/GoogleAds/Models/config.js
• Primary Use: Store API configuration, developer token settings

account

• Purpose: Validate account relationships and sub-accounts
• Model: external/models/account.js
• Usage: Verify parent-child account relationships for multi-tenant access

🔐 Authentication & Configuration

Authentication Method: OAuth 2.0

Required Environment Variables:

Variable	Description	Required
GOOGLE_CLIENT_ID	OAuth client ID	✅
GOOGLE_CLIENT_SECRET	OAuth client secret	✅
GOOGLE_ADS_REDIRECT_URL	OAuth callback URL (production)	✅
GOOGLE_ADS_CALLBACK_REDIRECT_URL	Post-auth redirect URL	✅
GOOGLE_ADS_DEVELOPER_TOKEN	Production manager developer token	✅
GOOGLE_ADS_API_VERSION	API version (e.g., v15)	✅
PROXY_URL	Development callback URL	⚠️ (dev only)

OAuth Scopes: https://www.googleapis.com/auth/adwords

Credential Storage:

• OAuth tokens stored in google-ads-token collection
• Tokens include:
  • access_token - Short-lived access token
  • refresh_token - Long-lived refresh token for token renewal
  • generated_at - Token generation timestamp
  • expires_in - Token lifetime in seconds
  • manager_id - MCC manager customer ID
  • client_id - Client customer ID

🏗️ Architecture Overview

Key Responsibilities:

• OAuth 2.0 authentication for Google Ads API access
• Campaign management (create, read, update, delete)
• Ad group operations
• Keyword management
• Ad creation and editing
• Performance metrics and analytics
• MCC (Manager account) operations for multi-client management

API Communication Pattern:

• OAuth 2.0 for authentication
• Google Ads API via third-party Node.js client (Opteo)
• REST API pattern with resource-based endpoints
• Pagination support via pageToken and pageSize

Resource Hierarchy:

Manager Account (MCC)
  └── Client Account
      └── Campaign
          └── Ad Group
              ├── Ads
              └── Keywords

Rate Limiting:

• Google Ads API enforces rate limits per developer token
• Limits vary by API version and account type
• SDK handles automatic retry with exponential backoff

🔗 Features & Capabilities

Core Features

• 📘 Authentication - OAuth flow, token refresh, account linking
• 📗 MCC Operations - Manager account and client listing
• 📙 Campaigns - Campaign CRUD operations and metrics
• 📕 Ad Groups - Ad group management and analytics
• 📓 Ads - Ad creation, editing, and performance tracking
• 📔 Keywords - Keyword management and metrics

🔄 Integration Data Flow

OAuth Authentication Flow

sequenceDiagram
    participant User
    participant DashClicks
    participant Google
    participant DB

    User->>DashClicks: GET /auth/login?forward_url
    DashClicks->>DashClicks: Create JWT state token
    DashClicks->>Google: Redirect to OAuth consent
    User->>Google: Grant permissions
    Google->>DashClicks: GET /auth/callback?code&state
    DashClicks->>DashClicks: Verify JWT state
    DashClicks->>Google: Exchange code for tokens
    Google-->>DashClicks: Return access_token & refresh_token
    DashClicks->>DB: Save tokens
    DashClicks-->>User: Redirect to forward_url?status=success

API Request Flow (Campaigns Example)

sequenceDiagram
    participant Client
    participant Controller
    participant TokenModel
    participant GoogleAdsAPI
    participant Cache

    Client->>Controller: GET /campaigns?clientID&managerID
    Controller->>TokenModel: Fetch OAuth tokens
    TokenModel-->>Controller: Return tokens
    alt Token Expired
        Controller->>GoogleAdsAPI: Refresh token
        GoogleAdsAPI-->>Controller: New access_token
        Controller->>TokenModel: Update token
    end
    Controller->>GoogleAdsAPI: List campaigns
    GoogleAdsAPI-->>Controller: Campaign data
    Controller-->>Client: Return campaigns JSON

📊 Query Parameters

Common Query Parameters Across Endpoints:

Parameter	Type	Required	Description
clientID	String	✅	Client customer ID (without hyphens)
managerID	String	✅	Manager customer ID (without hyphens)
campaignID	String	❌	Comma-separated campaign IDs
adGroupID	String	❌	Comma-separated ad group IDs
adID	String	❌	Comma-separated ad IDs
campaignType	Enum	❌	SEARCH, DISPLAY, SHOPPING, MULTI_CHANNEL
fromDate	String	❌	Start date (YYYY-MM-DD)
endDate	String	❌	End date (YYYY-MM-DD)
date	String	❌	Single date (YYYY-MM-DD)
searchText	String	❌	Search/filter text
sortField	String	❌	Field name for sorting
sortOrder	String	❌	ASC or DESC
pageSize	Number	❌	Results per page (default varies by endpoint)
pageToken	String	❌	Pagination token for next page

Date Filtering:

• Use date for single day queries
• Use fromDate and endDate for date ranges
• Format: YYYY-MM-DD (e.g., 2024-01-15)
• All dates in UTC

🔗 Submodules

• Authentication Flow - OAuth, token management
• MCC Operations - Manager account and client management
• Campaigns - Campaign operations and metrics
• Ad Groups - Ad group management
• Ads - Ad creation and performance
• Keywords - Keyword management and analytics

🚨 Error Handling

Common Error Scenarios:

OAuth Token Expired

• Error: 401 Unauthorized
• Handling: Automatic token refresh using refresh_token
• User Impact: Transparent - request retried automatically

Invalid Customer ID

• Error: 400 Bad Request
• Response: { success: false, message: "Invalid customer ID" }
• Handling: Validate format (digits only, no hyphens)

Developer Token Not Approved

• Error: 403 Forbidden
• Cause: Developer token pending approval from Google
• Resolution: Request approval in Google Ads API Center

Rate Limit Exceeded

• Error: 429 Too Many Requests
• Handling: SDK automatic retry with exponential backoff
• User Impact: Delayed response

Invalid Permissions

• Error: 403 Forbidden
• Cause: OAuth token lacks required permissions
• Resolution: Re-authenticate with correct scopes

📊 Campaign Types

Supported Campaign Types:

• UNKNOWN - Unknown type
• SEARCH - Search Network campaigns
• DISPLAY - Display Network campaigns
• SHOPPING - Shopping campaigns
• MULTI_CHANNEL - Multi-channel campaigns
• VIDEO - Video campaigns (YouTube)
• SMART - Smart campaigns

📈 Metrics Available

Standard Metrics (available for campaigns, ad groups, ads, keywords):

• Impressions
• Clicks
• CTR (Click-Through Rate)
• Cost
• Average CPC
• Conversions
• Conversion Rate
• Cost per Conversion
• Impressions Share
• Quality Score (keywords only)

For complete metrics reference, see Google Ads Metrics Documentation.

⚠️ Important Notes

• 🔐 Developer Token: Requires approved production manager account developer token
• 💰 API Costs: No direct API costs, but manages ad spend
• ⏱️ Rate Limits: Varies by API version and account type
• 🔄 Token Refresh: Automatic refresh using long-lived refresh tokens
• 📝 Logging: All operations logged with initiator external/Integrations/GoogleAds/
• 🚨 Customer ID Format: Always remove hyphens (1234-5678-9012 → 123456789012)
• 🎯 MCC Required: Many operations require manager account access

🔍 Development Setup

Test Account Requirements:

1. Production Manager Account

   • Create at Google Ads Manager Accounts
   • Obtain developer token from API Center
   • Used for: Developer token only

2. Test Manager Account

   • Create at Google Ads Test Accounts
   • Add test clients with campaigns
   • Used for: OAuth tokens and testing

Setup Steps:

1. Enable Google Ads API in Google API Console
2. Create OAuth 2.0 credentials
3. Set callback URL to GOOGLE_ADS_REDIRECT_URL
4. Get developer token from production manager account
5. Authenticate with test manager account for testing

🔗 Related Documentation

• Provider API Docs: Google Ads API Documentation
• Metrics Reference: Google Ads Metrics
• OAuth Documentation: Google OAuth 2.0
• Third-Party Client: Opteo Google Ads API

🎯 Integration Checklist

Before Using:

• Obtain production manager developer token
• Create OAuth 2.0 credentials
• Set all required environment variables
• Enable Google Ads API in Google Cloud Console
• Create test manager account for development
• Add test clients to test manager

When Connecting:

• Provide forward_url for post-auth redirect
• Ensure account has necessary permissions
• Validate customer ID format (no hyphens)

After Connection:

• Verify token storage in database
• Test token refresh mechanism
• Validate API access with test requests
• Monitor rate limit usage