# Google Ads API Tool Design Document

## 1. Overview

**Tool Name:** TOP2026-Ads Google Ads API Integration
**Purpose:** Internal advertising campaign management for insurance agent recruitment
**Developer:** 인카다이렉트 티오피사업단
**API Version:** Google Ads API v20

## 2. Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Internal CLI   │────▶│  GoogleAdsClient │────▶│ Google Ads  │
│  (google_ads_   │     │  (Python SDK)    │     │ API v20     │
│   cli.py)       │     │                  │     │             │
├─────────────────┤     ├──────────────────┤     ├─────────────┤
│  Dashboard      │────▶│  server.py       │────▶│ REST API    │
│  (Browser UI)   │     │  (Backend)       │     │ Endpoints   │
└─────────────────┘     └──────────────────┘     └─────────────┘
```

## 3. Authentication

- **OAuth 2.0** with refresh token (offline access)
- Credentials stored in server-side environment variables (.env.keys)
- No client-side credential exposure
- Refresh token auto-renewal (no manual intervention needed)

## 4. API Operations

### 4.1 Campaign Management (CRUD)
- List campaigns with status and budget
- Create campaigns (Search, Display, Performance Max)
- Update campaign status (ENABLED/PAUSED)
- Delete campaigns

### 4.2 Ad Group Management
- List ad groups within campaigns
- Create ad groups with targeting
- Update bids and status

### 4.3 Keyword Management
- Add/remove keywords
- Update keyword bids
- Get keyword performance

### 4.4 Ad Management
- Create responsive search ads
- Create display ads (image upload)
- Update ad status

### 4.5 Reporting & Insights
- Campaign performance reports (impressions, clicks, CTR, CPC, conversions)
- Ad group performance breakdown
- Keyword performance analysis
- Date range filtering

### 4.6 Account Information
- Account status and settings
- Budget utilization
- Billing information

## 5. Data Flow

1. User interacts via CLI or Dashboard
2. Backend (server.py) receives request
3. GoogleAdsClient authenticates via OAuth 2.0
4. GAQL query sent to Google Ads API
5. Response parsed and returned as JSON
6. Dashboard renders data with benchmarks

## 6. Security

- All API credentials stored in .env.keys (chmod 640)
- No credentials in source code or logs
- Token masking in CLI output (first 8...last 4 chars)
- HTTPS-only API communication

## 7. Rate Limits & Error Handling

- Google Ads API: 15,000 requests/day (Basic Access)
- Exponential backoff on rate limit errors
- Graceful degradation when API unavailable
- Error messages returned as structured JSON

## 8. Usage

### CLI
```bash
python3 scripts/google_ads_cli.py status
python3 scripts/google_ads_cli.py campaigns list
python3 scripts/google_ads_cli.py insights --campaign-id 123 --days 7
```

### Dashboard
- Campaign View > 구글광고현황 section
- Drill-down: Campaign > Ad Group > Ad
- Industry benchmark comparison
- Optimization suggestions

## 9. Access Scope

- **Internal use only** — employees of 인카다이렉트 티오피사업단
- No external user access
- Single Google Ads account (Customer ID: 494-475-2603)
- Manager account (MCC ID: 389-764-2742)