Google Ads¶

Overview¶

The Google Ads task integrates BaseCloud CRM with Google Ads API v24, enabling automated campaign analytics, offline conversion tracking, and custom reporting using GAQL (Google Ads Query Language).

Key Features:

• 3 Actions: Get metrics, upload offline conversions, custom GAQL queries
• OAuth 2.0 Authentication: Secure Google integration with automatic token refresh
• GAQL Support: SQL-like query language for advanced reporting
• Offline Conversions: Enhanced conversion tracking with hashed PII
• Metrics Aggregation: Campaign performance across date ranges
• Developer Token: Enterprise-level API access

Use Cases:

• Automated daily performance reporting
• Offline conversion import from CRM
• Custom analytics dashboards
• Budget optimization workflows
• Multi-account management
• ROAS tracking and alerts

Prerequisites¶

1. Google Ads Account¶

Requirements:

• Active Google Ads account
• Manager account (MCC) recommended for agencies
• Campaigns with conversion tracking enabled
• Admin access to Google Ads account

2. Google Cloud Project¶

Setup Google Cloud:

1. Go to https://console.cloud.google.com
2. Create new project or select existing
3. Enable Google Ads API
4. Create OAuth 2.0 credentials:
5. Application type: Web application
6. Authorized redirect URIs: https://yourapp.basecloudglobal.com/oauth/callback
7. Note Client ID and Client Secret

3. Google Ads Developer Token¶

Obtain Developer Token:

1. Sign in to Google Ads
2. Navigate to Tools & Settings → Setup → API Center
3. Apply for Developer Token
4. For testing: Use test account token
5. For production: Apply for Basic or Standard access
6. Approval process: 24-48 hours

Access Levels:

• Test Account: Limited to test account data
• Basic: Production access, rate limits apply
• Standard: Higher limits, requires spending threshold ($10,000+)

4. OAuth Configuration in BaseCloud¶

Create App Connection:

1. Navigate to BaseCloud CRM → Settings → App Connections
2. Click + New App Connection
3. Select Google Ads from dropdown
4. Enter credentials:
5. Client ID: From Google Cloud Console
6. Client Secret: From Google Cloud Console
7. Developer Token: From Google Ads API Center
8. Click Authorize with Google
9. Authorize scope: https://www.googleapis.com/auth/adwords
10. Select Google Ads account (Manager account if applicable)
11. Save connection

OAuth Scopes Required:

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

5. Customer ID and Account Structure¶

Get Customer IDs:

• Manager Account (MCC): 10-digit ID without hyphens (e.g., 1234567890)
• Client Accounts: Sub-account IDs under manager
• Found in Google Ads top right corner or account selector

Account Hierarchy:

Manager Account (MCC)
├── Client Account 1
├── Client Account 2
└── Client Account 3

For automation:

• Use Manager ID for multi-account access
• Use specific Account ID for single-account operations

Connections live in Settings → App Connections, not on the task. Connect the app once and every task that needs it can use it. The badge on each tile says how it authenticates — OAuth2 sends you to the provider to sign in, API Key expects a key you paste in.

Outputs¶

Reporting actions populate query, data and row_count; a conversion upload populates result.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: get_metrics¶

Retrieve aggregated campaign performance metrics for specified date range.

Date Range Options:

Available Metrics:

Basic Performance:

• impressions - Ad impressions
• clicks - Clicks on ads
• ctr - Click-through rate (calculated)
• average_cpc - Average cost per click
• cost - Total spend

Conversions:

• conversions - Total conversions
• conversions_value - Total conversion value
• conversion_rate - Conversion rate (calculated)
• cost_per_conversion - Cost per conversion
• conversions_from_interactions_rate - Conversion rate from interactions

All Conversions (includes view-through):

• all_conversions
• all_conversions_value
• all_conversions_from_interactions_rate
• cost_per_all_conversions
• value_per_all_conversions

Impression Share:

• search_impression_share - Percentage of eligible impressions received
• search_budget_lost_impression_share - Lost due to budget
• search_rank_lost_impression_share - Lost due to ad rank

Note: Calculated metrics (ctr, conversion_rate, etc.) are computed post-aggregation.

Output Variables:

task_35001_run; // true/false
task_35001_run_text; // "Metrics fetched."
task_35001_metrics; // Complete metrics object
task_35001_impressions; // Individual metric values
task_35001_clicks;
task_35001_ctr;
task_35001_cost;
task_35001_conversions;
// ... all requested metrics

How It Works:

1. Validates OAuth connection and developer token
2. Builds GAQL query: SELECT metrics.X FROM campaign WHERE segments.date DURING {range}
3. Fetches data from Google Ads API v24
4. Aggregates metrics across all campaigns
5. Calculates derived metrics (CTR, conversion rate, etc.)
6. Converts cost from micros to currency (÷ 1,000,000)
7. Returns unified metrics object

Example Metrics Object:

{
  impressions: 125000,
  clicks: 4500,
  ctr: 3.6,
  cost: 12500.50,
  average_cpc: 2.78,
  conversions: 450,
  conversions_value: 45000.00,
  conversion_rate: 10.0,
  cost_per_conversion: 27.79,
  search_impression_share: 85.5
}

Action 2: upload_offline_conversions¶

Upload offline conversion events to Google Ads for conversion tracking.

User Identifiers (at least ONE required):

Configure with setting_1 = 'upload_offline_conversions_identifier':

Additional Optional Fields:

Output Variables:

task_35001_run; // true/false
task_35001_run_text; // "Offline conversion uploaded successfully."
task_35001_result; // Upload result object
task_35001_result.success; // true/false
task_35001_result.message; // Status message

How It Works:

1. Validates required fields and at least one identifier
2. Hashes PII (email, phone) with SHA256 automatically
3. Builds conversion payload with user identifiers
4. Adds GDPR consent headers
5. Calls: POST https://datamanager.googleapis.com/v1/events:ingest (Data Manager API - versioned separately from the Google Ads API)
6. Returns success status

Click Identifiers vs Enhanced Conversions:

• With gclid/gbraid/wbraid: Standard click-based conversion
• Without click identifier: Enhanced conversion with hashed PII

Example Request:

{
  conversions: [{
    conversionAction: "customers/9876543210/conversionActions/123456789",
    conversionDateTime: "2024-02-08T14:30:00+00:00",
    conversionValue: 99.99,
    currencyCode: "USD",
    orderId: "ORDER-12345",
    gclid: "EAIaIQobChMI..." // Or userIdentifiers if no click ID
  }],
  partialFailure: true
}

GDPR Consent Headers:

consent-ad-user-data: GRANTED
consent-ad-personalization: GRANTED

Get Conversion Actions:

Use frontend dropdown or query:

SELECT conversion_action.id, conversion_action.name, conversion_action.type
FROM conversion_action
WHERE conversion_action.status = 'ENABLED'
  AND conversion_action.type IN ('WEBPAGE', 'UPLOAD_CLICKS', 'UPLOAD_CALLS')

Action 3: custom_query¶

Execute custom GAQL (Google Ads Query Language) queries for advanced reporting.

Output Variables:

task_35001_run; // true/false
task_35001_run_text; // "Custom query executed successfully."
task_35001_query; // Executed query string
task_35001_data; // Array of result objects
task_35001_row_count; // Number of rows returned

GAQL Query Examples:

Get Campaign Names and Performance:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 100

Get Ad Group Keywords:

SELECT
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM keyword_view
WHERE campaign.id = 12345
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.clicks DESC

Get Conversion Actions:

SELECT
  conversion_action.id,
  conversion_action.name,
  conversion_action.type,
  conversion_action.category,
  conversion_action.status
FROM conversion_action
WHERE conversion_action.status = 'ENABLED'

Get Ad Performance by Device:

SELECT
  ad_group_ad.ad.id,
  ad_group_ad.ad.name,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr
FROM ad_group_ad
WHERE segments.date DURING THIS_MONTH
  AND ad_group_ad.status = 'ENABLED'

Get Search Terms Report:

SELECT
  search_term_view.search_term,
  search_term_view.status,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 0
ORDER BY metrics.impressions DESC
LIMIT 500

GAQL Resources:

• campaign - Campaign-level data
• ad_group - Ad group data
• ad_group_ad - Individual ads
• ad_group_criterion - Keywords, placements
• keyword_view - Keyword performance
• search_term_view - Search query performance
• conversion_action - Conversion definitions
• customer - Account information

GAQL Segments:

• segments.date - Date dimension
• segments.device - Device type (MOBILE, DESKTOP, TABLET)
• segments.ad_network_type - Network (SEARCH, DISPLAY, YOUTUBE)
• segments.conversion_action - Conversion breakdown
• segments.hour - Hour of day

Documentation: https://developers.google.com/google-ads/api/fields/v24

Real-World Examples¶

Push an offline conversion when a deal is won¶

CRM Trigger  (status changed to "Won")
  └─ Match to Client   look the client up
      └─ Google Ads    upload the conversion

This is the main reason to use the task: telling Google which clicks became real revenue.

Pull campaign performance into a weekly email¶

Schedule  (weekly)
  └─ Google Ads   run a GAQL query for the last 7 days
      └─ Email    report {{task_35001_row_count}} rows of results

Record performance in a sheet¶

Schedule
  └─ Google Ads         run the report query
      └─ Loop           over {{task_35001.JSON.data}}, action: array
          └─ Google Sheets   append_row

Troubleshooting¶

Error: "No app connection selected"¶

Cause: OAuth connection not configured

Solutions:

1. Go to Settings → App Connections
2. Create Google Ads connection
3. Enter Client ID, Client Secret, and Developer Token
4. Complete OAuth authorization
5. Select connection in task dropdown

Error: "Developer token required"¶

Cause: Missing or invalid developer token in OAuth config

Solutions:

1. Obtain developer token from Google Ads API Center
2. Edit app connection in BaseCloud
3. Add developer token to OAuth configuration
4. For testing: Use test account token
5. For production: Apply for Basic/Standard access

Error: "Invalid customer ID"¶

Cause: Customer ID format incorrect or inaccessible

Solutions:

1. Use 10-digit ID without hyphens: 1234567890 (not 123-456-7890)
2. Verify account access in Google Ads
3. Use Manager Account (MCC) ID for multi-account access
4. Check OAuth connection has access to specified customer
5. Remove any special characters or spaces

Error: "Token expired" or 401 Unauthorized¶

Cause: OAuth access token expired

Solutions:

1. BaseCloud automatically refreshes tokens
2. If error persists, re-authorize app connection:
3. Settings → App Connections → Edit
4. Click Re-authorize with Google
5. Verify OAuth scope is correct: https://www.googleapis.com/auth/adwords
6. Check refresh token hasn't been revoked

Metrics List Empty or Invalid¶

Cause: metrics_list field is empty array '[]' or invalid JSON

Solutions:

1. Provide at least one metric: ["impressions"]
2. Use valid JSON array format with quotes
3. Check metric names match available options
4. Remove spaces from metric names
5. Valid example: ["impressions","clicks","cost"]

Custom Query Returns No Data¶

Cause: GAQL query syntax error or no matching data

Solutions:

1. Test query in Google Ads Query Builder first
2. Verify resource names (e.g., campaign, not campaigns)
3. Check date range has data
4. Validate WHERE clause filters
5. Use LIMIT to prevent large result sets
6. Check API field reference: https://developers.google.com/google-ads/api/fields/v24

Offline Conversion Upload Failed¶

Cause: Missing required identifiers or invalid format

Solutions:

1. Provide at least ONE identifier (gclid preferred)
2. Verify conversion action ID is correct (get from dropdown or custom query)
3. Check timestamp format: ISO 8601 with timezone (2024-02-08T14:30:00+00:00)
4. Validate value is numeric (no currency symbols)
5. Use valid currency code (USD, EUR, GBP, etc.)
6. Email/phone are auto-hashed, provide plain text
7. Check consent fields are: GRANTED, DENIED, or UNSPECIFIED

Error: "Conversion action not found"¶

Cause: Invalid conversion action ID or not uploadable type

Solutions:

1. Get conversion actions via custom query:

   SELECT conversion_action.id, conversion_action.name, conversion_action.type
   FROM conversion_action
   WHERE conversion_action.status = 'ENABLED'
   

2. Use conversion actions with types: WEBPAGE, UPLOAD_CLICKS, UPLOAD_CALLS
3. Cannot use PHONE_CALL_LEAD or STORE_VISIT types for API upload
4. Verify conversion action belongs to correct account

Rate Limiting / Quota Exceeded¶

Cause: Exceeded Google Ads API rate limits

Solutions:

1. Standard Access Limits:
2. 15,000 operations per day

3. Requests count against quota

4. Immediate Actions:

5. Add delays in bulk processing loops (2-5 seconds)
6. Reduce frequency of metric fetches

7. Cache results when possible

8. Long-term:

9. Apply for Standard Access (requires $10,000+ spend)
10. Use batch operations where possible
11. Implement exponential backoff on errors
12. Monitor quota usage in Google Cloud Console

Permission Denied on Specific Account¶

Cause: OAuth token doesn't have access to target account

Solutions:

1. Verify account hierarchy:
2. Manager account must link to client accounts
3. User must have access to manager account
4. Check Google Ads permissions:
5. Navigate to Tools → Access & Security → Users
6. Verify email has Admin or Standard access
7. Re-authorize OAuth connection
8. Use correct customer_id (manager) and account_id (client)

Best Practices¶

Authentication Management¶

1. Developer Token:
2. Store securely in OAuth config
3. Use test token for development/staging
4. Apply for production access before launch

5. Monitor approval status in API Center

6. OAuth Connections:

7. Create separate connections for dev/staging/production
8. Use descriptive names: "Google Ads - Main Account", "Google Ads - Client ABC"

9. Document which connection accesses which accounts

10. Token Refresh:

11. BaseCloud handles automatic refresh
12. Monitor for refresh failures
13. Re-authorize if persistent issues

Metrics Strategy¶

1. Metric Selection:
2. Request only needed metrics to reduce processing time
3. Use calculated metrics (CTR, conversion rate) instead of computing manually

4. Avoid mixing incompatible metrics in same query

5. Date Ranges:

6. Use presets when possible (faster than custom)
7. For historical analysis, use custom ranges

8. Be aware of data freshness (typically 3-hour delay)

9. Aggregation:

10. Metrics are aggregated across all campaigns by default
11. Use custom queries for campaign-level breakdown
12. Consider impression share metrics for competitive analysis

GAQL Best Practices¶

1. Query Optimization:
2. Select only needed fields
3. Use WHERE clauses to filter data
4. Add LIMIT to prevent oversized results

5. Order by relevant metrics

6. Resource Selection:

7. Use campaign for campaign-level data
8. Use ad_group_ad for ad-level data
9. Use keyword_view for keyword performance

10. Use search_term_view for actual search queries

11. Segmentation:

12. Add segments.date for daily breakdown
13. Use segments.device for device analysis
14. Include segments.ad_network_type for network split

Offline Conversion Best Practices¶

1. Identifier Strategy:
2. Preferred: Use gclid (Google Click ID)
3. Fallback: Enhanced conversions with email/phone
4. Store gclid in CRM on form submission

5. Validate identifier exists before upload

6. Data Quality:

7. Use accurate conversion timestamps
8. Provide actual conversion value (not estimated)
9. Include order IDs for deduplication

10. Set appropriate consent values

11. Conversion Actions:

12. Create specific actions for different conversion types
13. Use consistent naming: "Purchase - Website", "Lead - Phone"
14. Set appropriate counting methods (One per click vs Every)
15. Configure lookback windows appropriately

Performance Optimization¶

1. Caching:
2. Cache metric results for dashboards (hourly refresh)
3. Store conversion action lists (reload daily)

4. Cache account hierarchy (reload weekly)

5. Rate Limiting:

6. Add 2-5 second delays in multi-account loops
7. Batch operations when possible
8. Schedule large queries during off-peak

9. Implement exponential backoff for retries

10. Error Handling:

11. Wrap critical queries in If Conditions
12. Log failures for troubleshooting
13. Provide fallback workflows
14. Alert admins on persistent failures

Reporting Strategy¶

1. Automated Reports:
2. Daily performance summary (yesterday's data)
3. Weekly trends analysis (7-day rolling)
4. Monthly campaign reviews (full month)

5. Real-time alerts (budget, performance)

6. Data Storage:

7. Append metrics to a sheet with Google Sheets for historical trends
8. Create time-series data for visualization
9. Archive raw query results for auditing

10. Maintain client-level reporting tables

11. Stakeholder Communication:

12. Executive summary: High-level metrics (ROAS, conversions)
13. Marketing team: Detailed campaign performance
14. Finance: Spend tracking and budget adherence
15. Clients: Campaign-specific results

FAQ¶

Q: What's the difference between customer_id and account_id?

A:

• customer_id: Manager Account (MCC) ID - top-level account managing others
• account_id: Specific Google Ads account where ads run
• For single accounts: Both can be same ID
• For agencies: customer_id = MCC, account_id = client account

Q: Do I need a Manager Account (MCC)?

A:

• Not required for single account management
• Recommended for agencies or multi-account setups
• Benefits: Centralized billing, cross-account reporting, user management

Q: How long does it take for data to appear?

A:

• Performance data: Typically 3 hours delay
• Conversion data: Can take 24-48 hours
• Offline conversions: Usually within a few hours of upload

Q: What's a developer token and how do I get one?

A: Developer token authenticates API access. Get from Google Ads → Tools → API Center. Test tokens work immediately; production requires application approval (24-48 hours).

Q: Can I modify campaigns via API?

A: This task focuses on reporting and conversion upload. Campaign modification requires additional actions not currently implemented. Use Google Ads UI or consider custom development.

Q: What are micros and why does cost use them?

A: Google Ads API returns costs in micros (1/1,000,000 of currency). BaseCloud automatically converts: cost_micros / 1,000,000 = actual cost.

Q: How accurate is GAQL query execution?

A: GAQL queries execute directly against Google Ads API with same accuracy as Google Ads UI. Results match reporting UI but may have slight timestamp differences.

Q: Can I track phone call conversions?

A: Yes, using offline conversion upload with phone call conversion action. Store call details in CRM and upload with appropriate conversion action ID.

Q: What happens if I exceed rate limits?

A: API returns quota exceeded error. Implement delays between requests (2-5 seconds) and apply for Standard Access for higher limits.

Q: Can I access competitor data?

A: No, API only accesses accounts you manage. Use impression share metrics to gauge competitive landscape.

Q: How do I handle multi-currency accounts?

A: Specify currency in offline conversion uploads. For metrics, Google Ads converts to account currency automatically.

Q: Can I export data to Google Sheets?

A: Yes, use Google Sheets task after getting metrics. Store data in variables and write to sheets.

Related Tasks¶

• Facebook Marketing - Social media advertising analytics
• Google Sheets - Export metrics to spreadsheets
• Loop - Process multiple accounts
• If Statement - Conditional logic based on metrics
• Email - Send performance reports
• Variable - Calculate custom metrics (ROAS)

Technical Details¶

• Type ID: 35
• Function: taskGoogleAds() in automationService.js (lines 9795-10046)
• Service: googleAdsService.js (936 lines)
• API Version: Google Ads API v24 (sunsets ~May 2027)
• NPM Package: google-ads-api ^24.1.0 (the package major pins the API version)
• Authentication: OAuth 2.0 + Developer Token
• Scope: https://www.googleapis.com/auth/adwords
• Output Prefix: task_35001_*
• Rate Limits: 15,000 operations/day (Standard Access)
• GAQL Documentation: https://developers.google.com/google-ads/api/docs/query/overview
• API Reference: https://developers.google.com/google-ads/api/reference/rpc/v24