Jacek Pyziak
afe9d6216d
- Create migration for global settings table and add google_ads_customer_id and google_ads_start_date columns to clients table. - Add migration to include product_url column in products_data table. - Insert demo data for campaigns, products, and their history for client 'pomysloweprezenty.pl'. - Implement client management interface with modals for adding and editing clients, including Google Ads Customer ID and data retrieval start date.
154 lines
6.6 KiB
Plaintext
154 lines
6.6 KiB
Plaintext
<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns="http://www.w3.org/TR/REC-html40">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<style>
|
|
body { font-family: Calibri, sans-serif; font-size: 11pt; color: #333; line-height: 1.6; margin: 40px; }
|
|
h1 { font-size: 20pt; color: #1a73e8; border-bottom: 2px solid #1a73e8; padding-bottom: 8px; }
|
|
h2 { font-size: 14pt; color: #1a73e8; margin-top: 24px; }
|
|
h3 { font-size: 12pt; color: #444; margin-top: 16px; }
|
|
p { margin: 6px 0; }
|
|
ul { margin: 6px 0 6px 20px; }
|
|
li { margin: 4px 0; }
|
|
strong { color: #222; }
|
|
code { font-family: Consolas, monospace; font-size: 10pt; background: #f5f5f5; padding: 2px 4px; }
|
|
pre { font-family: Consolas, monospace; font-size: 9.5pt; background: #f8f8f8; border: 1px solid #ddd; padding: 12px; margin: 10px 0; white-space: pre-wrap; }
|
|
hr { border: none; border-top: 1px solid #ccc; margin: 16px 0; }
|
|
.meta { color: #666; font-size: 10pt; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<h1>adsPRO — Google Ads API Tool Design Documentation</h1>
|
|
|
|
<p class="meta"><strong>Company:</strong> Project-Pro<br>
|
|
<strong>Tool Name:</strong> adsPRO<br>
|
|
<strong>Date:</strong> February 2026<br>
|
|
<strong>Version:</strong> 1.0</p>
|
|
|
|
<hr>
|
|
|
|
<h2>1. Tool Overview</h2>
|
|
|
|
<p>adsPRO is an internal advertising management platform built for our agency to centralize and automate the management of Google Ads campaigns across multiple client accounts. The tool provides a unified dashboard for monitoring campaign performance, analyzing key metrics (ROAS, cost, conversion value), and managing campaign settings — eliminating the need to switch between multiple Google Ads accounts manually.</p>
|
|
|
|
<h2>2. Purpose and Business Use Case</h2>
|
|
|
|
<p>Our agency manages Google Ads campaigns for multiple clients. Currently, campaign data is collected manually or via Google Apps Script, which is fragile and hard to maintain. adsPRO replaces this workflow with a direct, reliable integration with the Google Ads API.</p>
|
|
|
|
<p><strong>Key goals:</strong></p>
|
|
<ul>
|
|
<li>Automatically retrieve campaign performance data for all managed client accounts</li>
|
|
<li>Display historical trends (ROAS, budget, spend, conversions) in a centralized dashboard</li>
|
|
<li>Enable campaign management operations (budget adjustments, bidding strategy changes, campaign status updates) directly from the platform</li>
|
|
<li>Reduce manual work and improve response time for campaign optimization</li>
|
|
</ul>
|
|
|
|
<h2>3. Google Ads API Usage</h2>
|
|
|
|
<h3>3.1 Data Retrieval (Read Operations)</h3>
|
|
|
|
<p>The tool uses the <strong>GoogleAdsService.SearchStream</strong> endpoint to fetch campaign data using GAQL (Google Ads Query Language).</p>
|
|
|
|
<p><strong>Data retrieved:</strong></p>
|
|
<ul>
|
|
<li>Campaign name, ID, and status</li>
|
|
<li>Bidding strategy type and target ROAS</li>
|
|
<li>Campaign budget (daily)</li>
|
|
<li>Cost (spend) over the last 30 days</li>
|
|
<li>Conversion value over the last 30 days</li>
|
|
<li>All-time ROAS calculation</li>
|
|
</ul>
|
|
|
|
<p><strong>GAQL queries used:</strong></p>
|
|
|
|
<pre>SELECT campaign.id, campaign.name, campaign.bidding_strategy_type,
|
|
campaign.target_roas.target_roas, campaign_budget.amount_micros,
|
|
metrics.cost_micros, metrics.conversions_value
|
|
FROM campaign
|
|
WHERE campaign.status = 'ENABLED'
|
|
AND segments.date DURING LAST_30_DAYS</pre>
|
|
|
|
<pre>SELECT campaign.id, metrics.cost_micros, metrics.conversions_value
|
|
FROM campaign
|
|
WHERE campaign.status = 'ENABLED'</pre>
|
|
|
|
<h3>3.2 Campaign Management (Write Operations)</h3>
|
|
|
|
<p>The tool will also support campaign management operations through the Google Ads API:</p>
|
|
|
|
<ul>
|
|
<li><strong>Budget adjustments</strong> — updating <code>campaign_budget.amount_micros</code> via <code>CampaignBudgetService.MutateCampaignBudgets</code></li>
|
|
<li><strong>Bidding strategy changes</strong> — modifying bidding strategy type and target ROAS via <code>CampaignService.MutateCampaigns</code></li>
|
|
<li><strong>Campaign status updates</strong> — enabling/pausing campaigns via <code>CampaignService.MutateCampaigns</code></li>
|
|
</ul>
|
|
|
|
<p>All write operations are initiated manually by authorized agency staff through the adsPRO interface. No automated modifications are made without human approval.</p>
|
|
|
|
<h2>4. API Request Frequency</h2>
|
|
|
|
<ul>
|
|
<li><strong>Automated data retrieval:</strong> Once per day via server-side CRON job (scheduled at 06:00 CET)</li>
|
|
<li><strong>Campaign management operations:</strong> On-demand, initiated manually by agency staff (estimated 10–50 requests per day)</li>
|
|
<li><strong>Number of client accounts:</strong> Currently under 20, expected to grow to ~50</li>
|
|
<li><strong>Estimated total daily API calls:</strong> Under 200 requests per day</li>
|
|
</ul>
|
|
|
|
<h2>5. Authentication and Authorization</h2>
|
|
|
|
<ul>
|
|
<li>OAuth 2.0 authentication with offline access (refresh token flow)</li>
|
|
<li>Credentials stored securely in a server-side database (not exposed to end users)</li>
|
|
<li>Access token is refreshed automatically when expired</li>
|
|
<li>Optional Manager Account (MCC) support for centralized access to client accounts</li>
|
|
</ul>
|
|
|
|
<h2>6. Architecture</h2>
|
|
|
|
<pre>[CRON - daily at 06:00]
|
|
|
|
|
v
|
|
[adsPRO Server (PHP)]
|
|
|
|
|
v
|
|
[Google Ads REST API v18]
|
|
- SearchStream (read campaign data)
|
|
- MutateCampaigns (manage campaigns)
|
|
- MutateCampaignBudgets (adjust budgets)
|
|
|
|
|
v
|
|
[MySQL Database]
|
|
- campaigns table (current state)
|
|
- campaigns_history table (daily snapshots)
|
|
|
|
|
v
|
|
[adsPRO Dashboard]
|
|
- Campaign performance charts
|
|
- ROAS tracking over time
|
|
- Campaign management interface</pre>
|
|
|
|
<h2>7. Data Handling and Privacy</h2>
|
|
|
|
<ul>
|
|
<li>All data is stored on our own private server (shared hosting with SSL)</li>
|
|
<li>Data is accessible only to authenticated agency staff (login required)</li>
|
|
<li>No campaign data is shared with third parties</li>
|
|
<li>No personally identifiable information (PII) is collected from end users</li>
|
|
<li>API credentials are stored server-side and never exposed in client-facing code</li>
|
|
</ul>
|
|
|
|
<h2>8. Users</h2>
|
|
|
|
<p>This is an <strong>internal agency tool</strong>. It is not a publicly available application. Access is restricted to authorized staff members of our agency (currently 3 users). There is no self-registration — accounts are created by the administrator.</p>
|
|
|
|
<h2>9. Compliance</h2>
|
|
|
|
<ul>
|
|
<li>The tool complies with the Google Ads API Terms of Service</li>
|
|
<li>The tool complies with the Google API Services User Data Policy</li>
|
|
<li>No data is sold or shared with third parties</li>
|
|
<li>The tool does not perform automated campaign modifications without human oversight</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|