@agentapps/app.google.ads 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -2
- package/agentapp.json +52 -0
- package/dist/app.js +24415 -0
- package/package.json +30 -4
package/README.md
CHANGED
|
@@ -1,3 +1,116 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Google Ads
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Lets an agent work with Google Ads accounts through the [Google Ads API](https://developers.google.com/google-ads/api/docs/start)
|
|
4
|
+
(REST, version **v26**, plain `fetch`, no SDK). It lists the accounts a Google user can reach,
|
|
5
|
+
directly or through manager (MCC) accounts, reports on account, campaign, ad group, ad,
|
|
6
|
+
keyword and search term performance, runs read-only GAQL queries, and makes a small set of
|
|
7
|
+
changes: pause or enable campaigns and ad groups, change a campaign budget, add negative
|
|
8
|
+
keywords. It does not create campaigns, ads or keywords, and it does not remove anything.
|
|
9
|
+
|
|
10
|
+
Limits: reports return at most 500 rows (1,000 accounts for `list-client-accounts`) and stay
|
|
11
|
+
under about 45,000 characters; each call gives up after 30 s. Google applies a daily operation
|
|
12
|
+
quota per developer token (see Setup). Money in results is in the account currency, not micros,
|
|
13
|
+
except in the raw rows of `run-gaql-query`.
|
|
14
|
+
|
|
15
|
+
## Tools
|
|
16
|
+
|
|
17
|
+
| Tool | What it does | Writes? |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `list-accessible-customers` | Accounts the connected user can reach directly; flags manager accounts | no |
|
|
20
|
+
| `list-client-accounts` | Client accounts under a manager account, and the `loginCustomerId` to use for them | no |
|
|
21
|
+
| `get-account-summary` | Account details and total metrics for a date range | no |
|
|
22
|
+
| `list-campaigns` | Campaigns with status, channel, bidding strategy and budget (no metrics) | no |
|
|
23
|
+
| `list-campaign-budgets` | Budgets with amount, period and how many campaigns share each | no |
|
|
24
|
+
| `get-performance-report` | Metrics per campaign, ad group, ad or keyword, optionally per day | no |
|
|
25
|
+
| `get-search-terms-report` | The search queries that triggered ads, with the matched keyword | no |
|
|
26
|
+
| `run-gaql-query` | Any read-only GAQL `SELECT`, with paging | no |
|
|
27
|
+
| `pause-campaign` | Pause a campaign (stops spend; reversible) | yes |
|
|
28
|
+
| `enable-campaign` | Enable a campaign. **Affects spend**, marked destructive | yes |
|
|
29
|
+
| `pause-ad-group` | Pause an ad group (reversible) | yes |
|
|
30
|
+
| `enable-ad-group` | Enable an ad group. **Affects spend**, marked destructive | yes |
|
|
31
|
+
| `update-campaign-budget` | Set a budget amount. **Affects spend**, marked destructive | yes |
|
|
32
|
+
| `add-negative-keywords` | Add up to 100 negative keywords to a campaign or ad group | yes |
|
|
33
|
+
|
|
34
|
+
All write tools are `sensitive` (the host asks before running them) and accept
|
|
35
|
+
`validateOnly: true`, which makes Google check the change without applying it. Date ranges are
|
|
36
|
+
a preset (`dateRange`, default `LAST_30_DAYS`) or `startDate` + `endDate` (`YYYY-MM-DD`), in
|
|
37
|
+
the account's time zone.
|
|
38
|
+
|
|
39
|
+
### Manager accounts and `loginCustomerId`
|
|
40
|
+
|
|
41
|
+
Every tool that works on an account takes `customerId` (10 digits, dashes allowed) and an
|
|
42
|
+
optional `loginCustomerId`. When the connected Google user reaches an account only through a
|
|
43
|
+
manager (MCC) account, Google needs that manager's ID in the `login-customer-id` header: pass
|
|
44
|
+
it as `loginCustomerId`. It is a tool parameter rather than a setting because one user often
|
|
45
|
+
works with several managers, and a per-installation secret would have to be set (to a
|
|
46
|
+
placeholder) even by users without one. `list-accessible-customers` shows which accounts are
|
|
47
|
+
managers and `list-client-accounts` returns the `loginCustomerId` to use for each client. A
|
|
48
|
+
`USER_PERMISSION_DENIED` error says when it is missing.
|
|
49
|
+
|
|
50
|
+
## Setup
|
|
51
|
+
|
|
52
|
+
The app uses Google OAuth plus a Google Ads developer token. You need:
|
|
53
|
+
|
|
54
|
+
1. **A Google Cloud project** with the **Google Ads API** enabled
|
|
55
|
+
(APIs & Services > Library > Google Ads API).
|
|
56
|
+
2. **An OAuth client** in that project (APIs & Services > Credentials > Create credentials >
|
|
57
|
+
OAuth client ID, type *Web application*), with the station callback as an authorised
|
|
58
|
+
redirect URI: `<station publicUrl>/auth/callback`. This gives `CLIENT_ID` and `CLIENT_SECRET`.
|
|
59
|
+
3. **The OAuth consent screen** with the scopes `https://www.googleapis.com/auth/adwords` and
|
|
60
|
+
`https://www.googleapis.com/auth/userinfo.email`. `adwords` is a sensitive scope: while the
|
|
61
|
+
app is in *Testing* only the listed test users can connect and their refresh tokens expire
|
|
62
|
+
after 7 days; for real users Google must verify the app (Publish app, then verification).
|
|
63
|
+
4. **A developer token** (`DEVELOPER_TOKEN`) from a Google Ads **manager** account: Admin >
|
|
64
|
+
API Center ([guide](https://developers.google.com/google-ads/api/docs/get-started/dev-token)).
|
|
65
|
+
A new token has *Test* access (test accounts only). Production accounts need *Explorer*
|
|
66
|
+
(2,880 operations a day), *Basic* (15,000 a day, after brand verification) or *Standard*
|
|
67
|
+
(unlimited, after a compliance review), each applied for from the API Center
|
|
68
|
+
([access levels](https://developers.google.com/google-ads/api/docs/api-policy/access-levels)).
|
|
69
|
+
Use the token with the OAuth client of the same Google Cloud project.
|
|
70
|
+
5. **The customer IDs** you will work with: the 10-digit number at the top of the Google Ads
|
|
71
|
+
UI (`123-456-7890`), and the manager account ID when you access clients through one.
|
|
72
|
+
`list-accessible-customers` finds them too.
|
|
73
|
+
|
|
74
|
+
System secrets (shared by every installation, set on the app id):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
agentapps config app.google.ads CLIENT_ID:"<oauth client id>"
|
|
78
|
+
agentapps config app.google.ads CLIENT_SECRET:"<oauth client secret>"
|
|
79
|
+
agentapps config app.google.ads REDIRECT_URI:"https://your-station.example.com/auth/callback"
|
|
80
|
+
agentapps config app.google.ads DEVELOPER_TOKEN:"<developer token>"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`REDIRECT_URI` is only needed when `agentapps.json` has no `station.publicUrl`.
|
|
84
|
+
|
|
85
|
+
Then install an instance and connect a Google account (installation secrets belong to the alias;
|
|
86
|
+
`ACCESS_TOKEN`, `REFRESH_TOKEN`, `EMAIL` and `EXPIRY_DATE` are written by the OAuth flow, not
|
|
87
|
+
by hand):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
agentapps install app.google.ads google-ads
|
|
91
|
+
agentapps google-ads auth
|
|
92
|
+
agentapps google-ads tool list-accessible-customers
|
|
93
|
+
agentapps google-ads tool get-performance-report customerId:123-456-7890 dateRange:LAST_7_DAYS
|
|
94
|
+
agentapps google-ads tool list-client-accounts customerId:987-654-3210
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
If you ever need to set a user secret by hand, use the alias, not the app id:
|
|
98
|
+
`agentapps config google-ads KEY:value`.
|
|
99
|
+
|
|
100
|
+
## Terms of use
|
|
101
|
+
|
|
102
|
+
Use of the Google Ads API is governed by the
|
|
103
|
+
[Google Ads API Terms and Conditions](https://developers.google.com/google-ads/api/terms) and
|
|
104
|
+
the [Google Ads API policies](https://developers.google.com/google-ads/api/docs/api-policy/developer-token):
|
|
105
|
+
the developer token belongs to whoever applied for it, its daily operation quota applies to all
|
|
106
|
+
users of that token, and tools built on it must not be used to break the
|
|
107
|
+
[Google Ads policies](https://support.google.com/adspolicy/answer/6008942). Spend caused by
|
|
108
|
+
`enable-campaign`, `enable-ad-group` or `update-campaign-budget` is billed to the advertiser
|
|
109
|
+
account as usual.
|
|
110
|
+
|
|
111
|
+
## Logos
|
|
112
|
+
|
|
113
|
+
| File | Source | Changes |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| assets/logo.svg | Google's official Google Ads product logo, `https://www.gstatic.com/images/branding/productlogos/ads/v5/192px.svg` (Google's product-logo CDN; the same file `ads.google.com/home/` shows as the Google Ads icon) | none |
|
|
116
|
+
| assets/logo-mono.svg | the same file | removed the three `fill="#..."` colour attributes; the transparent bounding `rect fill="none"` and every shape are unchanged |
|
package/agentapp.json
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "app.google.ads",
|
|
3
|
+
"name": "Google Ads",
|
|
4
|
+
"version": "1.0.1",
|
|
5
|
+
"description": "Google Ads API (REST, v26): list the accounts a Google user can reach (including through manager accounts), report on account, campaign, ad group, ad, keyword and search term performance, run read-only GAQL queries, pause or enable campaigns and ad groups, change campaign budgets and add negative keywords. Writes that can spend money are marked destructive.",
|
|
6
|
+
"tagline": "Report on Google Ads performance and manage campaigns, budgets and negative keywords",
|
|
7
|
+
"author": { "name": "Pablo López Torres", "email": "pablolopeztorres@gmail.com" },
|
|
8
|
+
"license": "MIT",
|
|
9
|
+
"logo": "assets/logo.svg",
|
|
10
|
+
"logoMono": "assets/logo-mono.svg",
|
|
11
|
+
"terms": "https://agentapps.tech/terms",
|
|
12
|
+
"category": "google",
|
|
13
|
+
"keywords": [
|
|
14
|
+
"google",
|
|
15
|
+
"google-ads",
|
|
16
|
+
"adwords",
|
|
17
|
+
"ads",
|
|
18
|
+
"ppc",
|
|
19
|
+
"sem",
|
|
20
|
+
"marketing",
|
|
21
|
+
"advertising",
|
|
22
|
+
"campaigns",
|
|
23
|
+
"gaql"
|
|
24
|
+
],
|
|
25
|
+
"entrypoint": {
|
|
26
|
+
"type": "module",
|
|
27
|
+
"path": "src/app.ts",
|
|
28
|
+
"export": "factory"
|
|
29
|
+
},
|
|
30
|
+
"runtime": {
|
|
31
|
+
"transport": "stdio",
|
|
32
|
+
"command": "tsx",
|
|
33
|
+
"args": ["src/app.ts"]
|
|
34
|
+
},
|
|
35
|
+
"capabilities": {
|
|
36
|
+
"tools": true,
|
|
37
|
+
"health": true
|
|
38
|
+
},
|
|
39
|
+
"auth": {
|
|
40
|
+
"type": "oauth2",
|
|
41
|
+
"provider": "google",
|
|
42
|
+
"systemSecrets": ["CLIENT_ID", "CLIENT_SECRET", "REDIRECT_URI", "DEVELOPER_TOKEN"],
|
|
43
|
+
"installationSecrets": ["ACCESS_TOKEN", "REFRESH_TOKEN", "EMAIL", "EXPIRY_DATE"],
|
|
44
|
+
"authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth",
|
|
45
|
+
"tokenUrl": "https://oauth2.googleapis.com/token",
|
|
46
|
+
"scopes": [
|
|
47
|
+
"https://www.googleapis.com/auth/adwords",
|
|
48
|
+
"https://www.googleapis.com/auth/userinfo.email"
|
|
49
|
+
],
|
|
50
|
+
"pkce": false
|
|
51
|
+
}
|
|
52
|
+
}
|