Google Ads

Name: Google Ads
Rating: 3.5 (1 reviews)
Author: jugs-eth

By jugs-eth 👁 26 views ▲ 0 votes

OpenClaw Google Ads plugin

GitHub

Install

npm install
   ```

Configuration Example

{
  "results": [
    {
      "campaign": {
        "id": "123456789",
        "name": "Holiday Sale 2024",
        "status": "ENABLED",
        "advertising_channel_type": "SEARCH"
      },
      "metrics": {
        "impressions": "15420",
        "clicks": "832",
        "cost_micros": "4567890000",
        "ctr": "5.39",
        "conversions": "23"
      }
    }
  ]
}

README

# Google Ads CLI Plugin for OpenClaw

A comprehensive command-line interface for Google Ads that enables campaign management, optimization, and analytics through the Google Ads API v18.

## Features

- **Campaign Management**: Create, update, pause, enable campaigns
- **Ad Group Control**: Manage ad groups within campaigns
- **Keyword Management**: Add, remove, and optimize keywords
- **Ad Creation**: Create responsive search ads with multiple headlines/descriptions
- **Budget Control**: Update daily budgets and monitor spend
- **Performance Analytics**: Get detailed metrics and generate reports
- **Automated Optimization**: Tools for campaign performance optimization
- **Bulk Operations**: Manage multiple campaigns and ad groups efficiently

## Quick Start

1. **Install dependencies**:
   ```bash
   cd /root/.openclaw/workspace/skills/google-ads
   npm install
   ```

2. **Set up credentials** (see [Setup Guide](./setup.md)):
   Add to `/root/.openclaw/.env`:
   ```bash
   GOOGLE_ADS_CUSTOMER_ID=1234567890
   GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
   GOOGLE_ADS_CLIENT_ID=your_oauth_client_id
   GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret
   GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
   ```

3. **Test the connection**:
   ```bash
   ./google-ads.sh campaigns-list
   ```

## Commands

### Campaign Management

```bash
# List all campaigns with performance metrics
./google-ads.sh campaigns-list

# Create a new search campaign
./google-ads.sh campaign-create "Holiday Sale 2024" 100 MAXIMIZE_CLICKS

# Update campaign name
./google-ads.sh campaign-update 123456789 name:"New Campaign Name"

# Pause/enable campaigns
./google-ads.sh campaign-pause 123456789
./google-ads.sh campaign-enable 123456789

# Update daily budget
./google-ads.sh budget-update 123456789 150
```

### Ad Group & Keyword Management

```bash
# List ad groups in a campaign
./google-ads.sh adgroups-list 123456789

# Create new ad group with $1.50 max CPC
./google-ads.sh adgroup-create 123456789 "Running Shoes" 1500000

# List keywords in ad group
./google-ads.sh keywords-list 987654321

# Add keywords with different match types
./google-ads.sh keyword-add 987654321 "running shoes" EXACT
./google-ads.sh keyword-add 987654321 "athletic footwear" PHRASE
./google-ads.sh keyword-add 987654321 "sports shoes" BROAD

# Remove underperforming keyword
./google-ads.sh keyword-remove 987654321 444555666
```

### Ad Creation & Management

```bash
# List ads in ad group
./google-ads.sh ads-list 987654321

# Create responsive search ad
./google-ads.sh ad-create 987654321 \
  "https://shop.example.com/shoes" \
  "Best Running Shoes,Top Athletic Footwear,Premium Sports Shoes" \
  "Find your perfect running shoe,Quality footwear for athletes"

# Pause underperforming ad
./google-ads.sh ad-pause 987654321 111222333
```

### Analytics & Reporting

```bash
# Get metrics for specific date range
./google-ads.sh metrics 2024-01-01 2024-01-31

# Get metrics for specific campaign
./google-ads.sh metrics 2024-01-01 2024-01-31 123456789

# Generate summary reports
./google-ads.sh report 7    # Last 7 days
./google-ads.sh report 30   # Last 30 days
```

## Advanced Usage

### Campaign Optimization Workflow

**Performance Analysis**:
```bash
# Get monthly performance summary
./google-ads.sh report 30 > monthly_performance.json

# Identify top performing campaigns
jq '.campaigns[] | select(.ctr > 3.0 and .conversions > 10) | {name, ctr, conversions, cost}' monthly_performance.json

# Find underperforming campaigns
jq '.campaigns[] | select(.ctr < 1.0 or (.cost > 100 and .conversions == 0)) | {name, ctr, conversions, cost}' monthly_performance.json
```

**Budget Optimization**:
```bash
# Increase budget for top performers
./google-ads.sh budget-update 123456789 200  # High converting campaign
./google-ads.sh budget-update 987654321 75   # Reduce budget for poor performer

# Pause campaigns with no conversions and high spend
./google-ads.sh campaign-pause 555666777
```

**Keyword Expansion**:
```bash
# Add related keywords to successful ad groups
./google-ads.sh keyword-add 987654321 "marathon shoes" EXACT
./google-ads.sh keyword-add 987654321 "trail running shoes" PHRASE
./google-ads.sh keyword-add 987654321 "professional running gear" BROAD

# Create new ad variations for expanded keywords
./google-ads.sh ad-create 987654321 "https://shop.example.com/trail-shoes" \
  "Trail Running Shoes,Off-Road Athletic Footwear,Adventure Running Gear" \
  "Conquer any terrain with our trail shoes,Built for outdoor adventures"
```

### Automated Monitoring & Alerts

**Daily Performance Check**:
```bash
#!/bin/bash
# daily_ads_check.sh - Add to cron for daily monitoring

REPORT=$(./google-ads.sh report 1)
TOTAL_COST=$(echo $REPORT | jq -r '.total_cost')
TOTAL_CONVERSIONS=$(echo $REPORT | jq -r '.total_conversions')
AVG_CTR=$(echo $REPORT | jq -r '.average_ctr')

# Alert if spend is high but conversions are low
if (( $(echo "$TOTAL_COST > 500" | bc -l) )) && (( $(echo "$TOTAL_CONVERSIONS < 5" | bc -l) )); then
  echo "ALERT: High spend ($TOTAL_COST) with low conversions ($TOTAL_CONVERSIONS)"
fi

# Alert if CTR drops below threshold
if (( $(echo "$AVG_CTR < 2.0" | bc -l) )); then
  echo "ALERT: CTR dropped to $AVG_CTR% - consider ad optimization"
fi
```

**Automated Budget Management**:
```bash
#!/bin/bash
# auto_budget_optimizer.sh

# Get top performing campaigns (high CTR, good conversion rate)
HIGH_PERFORMERS=$(./google-ads.sh report 7 | jq -r '.campaigns[] | select(.ctr > 4.0 and .conversions > 5) | .id')

# Increase their budgets by 20%
for CAMPAIGN_ID in $HIGH_PERFORMERS; do
  CURRENT_BUDGET=$(./google-ads.sh campaigns-list | jq -r ".results[] | select(.campaign.id == \"$CAMPAIGN_ID\") | .campaign.campaign_budget")
  NEW_BUDGET=$(echo "$CURRENT_BUDGET * 1.2" | bc)
  ./google-ads.sh budget-update $CAMPAIGN_ID $NEW_BUDGET
  echo "Increased budget for campaign $CAMPAIGN_ID to $NEW_BUDGET"
done
```

### Data Export & Integration

**Export to CSV for Analysis**:
```bash
# Campaign performance CSV
./google-ads.sh campaigns-list | jq -r '.results[] | [
  .campaign.name, 
  .campaign.status, 
  .metrics.impressions, 
  .metrics.clicks, 
  (.metrics.cost_micros | tonumber / 1000000), 
  .metrics.conversions,
  (.metrics.ctr | tonumber)
] | @csv' > campaigns_performance.csv

# Keyword performance CSV
./google-ads.sh keywords-list 123456789 | jq -r '.results[] | [
  .ad_group.name,
  .ad_group_criterion.keyword.text,
  .ad_group_criterion.keyword.match_type,
  .metrics.impressions,
  .metrics.clicks,
  (.metrics.cost_micros | tonumber / 1000000)
] | @csv' > keywords_performance.csv
```

**Integration with External Tools**:
```bash
# Send daily report to Slack webhook
./google-ads.sh report 1 | curl -X POST $SLACK_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text": "Daily Google Ads Report", "attachments": [{"text": "'$(cat)'""}]}'

# Upload performance data to Google Sheets (via API)
./google-ads.sh metrics $(date -d '7 days ago' +%Y-%m-%d) $(date +%Y-%m-%d) > /tmp/ads_data.json
# Process and upload to sheets...

# Trigger optimization workflows
./google-ads.sh report 7 | python3 optimization_analyzer.py
```

## Rate Limits & Best Practices

### Google Ads API Rate Limits
- **Standard Operations**: 30,000 requests per minute
- **Report Downloads**: 50,000 requests per day
- **Mutations**: Varies by account (typically 5,000-50,000 per day)

### Best Practices
- **Batch Operations**: Use bulk mutations when possible
- **Efficient Queries**: Request only needed fields in reports
- **Caching**: Cache frequently accessed data like campaign lists
- **Error Handling**: Implement retry logic for temporary failures
- **Monitoring**: Set up alerts for quota usage

### Performance Optimization
```bash
# Use specific field selections for faster queries
./google-ads.sh campaigns-list | jq '.results[] | {name: .campaign.name, status: .campaign.status, cost: .metrics.cost_micros}'

# Batch keyword additions
echo "keyword1 EXACT
keyword2 PHRASE  
keyword3 BROAD" | while read keyword match_type; do
  ./google-ads.sh keyword-add 123456789 "$keyword" "$match_type"
done
```

## Output Format

All commands return structured JSON for easy parsing and integration:

**Campaign List Output**:
```json
{
  "results": [
    {
      "campaign": {
        "id": "123456789",
        "name": "Holiday Sale 2024",
        "status": "ENABLED",
        "advertising_channel_type": "SEARCH"
      },
      "metrics": {
        "impressions": "15420",
        "clicks": "832",
        "cost_micros": "4567890000",
        "ctr": "5.39",
        "conversions": "23"
      }
    }
  ]
}
```

**Error Format**:
```json
{
  "error": "Google Ads API error: Invalid customer ID"
}
```

## Troubleshooting

### Common Issues

**Authentication Errors**:
- Verify all OAuth credentials are correct
- Ensure refresh token hasn't expired (regenerate if needed)
- Check that Customer ID format is correct (numbers only, no dashes)

**API Access Issues**:
- Confirm Google Ads account has API access enabled
- Verify developer token is approved for production use
- Check that billing is set up on the Google Ads account

**Permission Errors**:
- Ensure OAuth scope includes Google Ads API access
- Verify account has necessary permissions for the operations
- Check if account is properly linked to the Customer ID

**Rate Limiting**:
- Implement delays between bulk operations
- Use batch operations when available
- Monitor quota usage in Google Cloud Console

### Debug Mode

Enable detailed logging for troubleshooting:

```bash
# Set debug environment variable
DEBUG=google-ads:* ./google-ads.sh campaigns-list

# Check API response details
./google-ads.sh campaigns-list 2>&1 | jq .
```

## Setup Guide

For detailed credential setup instructions, see [setup.md](./setup.md).

## Deploy with PinchKit

Deploy this Google Ads CLI plugin to your PinchKit infrastructure:

1. **Package the plugin**:
   ```bash
   cd /root/.openclaw/workspace/skill

... (truncated)

tools