@agentapps/app.meta-ads 1.0.0 → 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 +164 -0
- package/agentapp.json +1 -1
- package/dist/app.js +2 -2
- package/package.json +21 -1
package/README.md
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Meta Ads
|
|
2
|
+
|
|
3
|
+
Lets an agent report on and manage Meta (Facebook and Instagram) advertising through the
|
|
4
|
+
[Meta Marketing API](https://developers.facebook.com/docs/marketing-api), Graph API **v26.0**.
|
|
5
|
+
It lists ad accounts, campaigns, ad sets, ads and creatives, runs performance reports
|
|
6
|
+
(Ads Insights) at any level with date ranges, daily series and breakdowns, pauses and
|
|
7
|
+
activates delivery, changes budgets, and creates campaigns and ad sets. New campaigns and ad
|
|
8
|
+
sets are always created **paused**. Creating ads (images, video, Page posts) is not
|
|
9
|
+
supported: finish ads in Ads Manager.
|
|
10
|
+
|
|
11
|
+
Every write asks for approval by default. The tools that can make you spend money
|
|
12
|
+
(`activate-ad-object`, `update-budget`) are marked destructive and say so in their
|
|
13
|
+
descriptions.
|
|
14
|
+
|
|
15
|
+
## Tools
|
|
16
|
+
|
|
17
|
+
| Tool | What it does | Writes? |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `list-ad-accounts` | Ad accounts the token can use: id, name, status, currency, time zone, amount spent | no |
|
|
20
|
+
| `list-campaigns` | Campaigns of an account: objective, status, effective status, budgets, bid strategy | no |
|
|
21
|
+
| `list-ad-sets` | Ad sets of a campaign or account: budgets, optimisation goal, billing, schedule, targeting on request | no |
|
|
22
|
+
| `list-ads` | Ads of an ad set, campaign or account, with their creative and delivery issues | no |
|
|
23
|
+
| `list-creatives` | Ad creatives of an account: title, body, thumbnail, call to action | no |
|
|
24
|
+
| `get-insights` | Performance report for an account, campaign, ad set or ad: spend, impressions, reach, clicks, CTR, CPC, CPM or any Insights field; level, date preset or range, daily/weekly/monthly series, breakdowns, sort | no |
|
|
25
|
+
| `pause-ad-object` | Pause a campaign, ad set or ad (stops spend; reversible) | yes |
|
|
26
|
+
| `activate-ad-object` | Activate a campaign, ad set or ad. **Starts spending money** (destructive) | yes |
|
|
27
|
+
| `update-budget` | Change the daily or lifetime budget of a campaign or ad set. **Affects spend** (destructive) | yes |
|
|
28
|
+
| `create-campaign` | Create a campaign, always PAUSED, with or without a campaign budget | yes |
|
|
29
|
+
| `create-ad-set` | Create an ad set in a campaign, always PAUSED, with targeting and budget | yes |
|
|
30
|
+
|
|
31
|
+
Before any status or budget change the app reads the object with a field only that kind of
|
|
32
|
+
object has, so a write meant for an ad never lands on an ad set. Budgets are integers in the
|
|
33
|
+
account currency's minor units (cents: `5000` = 50.00); Insights `spend` is in major units.
|
|
34
|
+
|
|
35
|
+
## Setup
|
|
36
|
+
|
|
37
|
+
The app needs one user secret, `META_ACCESS_TOKEN`, and no system secrets.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
agentapps install app.meta-ads meta-ads
|
|
41
|
+
agentapps config meta-ads META_ACCESS_TOKEN:"<token>"
|
|
42
|
+
agentapps meta-ads tools
|
|
43
|
+
agentapps meta-ads tool list-ad-accounts
|
|
44
|
+
agentapps meta-ads tool get-insights id:act_1234567890 level:campaign datePreset:last_7d
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Installation secrets are per installation: set them on the alias (`meta-ads` above), not on
|
|
48
|
+
`app.meta-ads`. (`agentapps config app.meta-ads KEY:value` sets system secrets shared by every
|
|
49
|
+
installation; this app declares none.)
|
|
50
|
+
|
|
51
|
+
Campaign, ad set and ad ids have up to 18 digits, more than a JavaScript number holds. The
|
|
52
|
+
CLI turns `id:120210000000000001` into a rounded number, which the app rejects. Pass such
|
|
53
|
+
calls as one JSON object instead, which keeps strings:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
agentapps meta-ads tool pause-ad-object '{"level":"campaign","id":"120210000000000001"}'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Getting `META_ACCESS_TOKEN` (recommended: a System User token)
|
|
60
|
+
|
|
61
|
+
A System User token belongs to your business, not to a person, and does not expire. It can
|
|
62
|
+
reach exactly the ad accounts you assign to the System User.
|
|
63
|
+
|
|
64
|
+
1. **Business portfolio.** You need a Meta business portfolio
|
|
65
|
+
([business.facebook.com](https://business.facebook.com)) that owns, or has partner access
|
|
66
|
+
to, the ad accounts. You need admin rights in it.
|
|
67
|
+
2. **Meta app.** At [developers.facebook.com/apps](https://developers.facebook.com/apps),
|
|
68
|
+
create a Business app, add the Marketing API (the ads management use case) and connect the
|
|
69
|
+
app to the business portfolio. No App Review is needed to manage your own business's ad
|
|
70
|
+
accounts: standard access to `ads_read` and `ads_management` is enough. Leave **Require App Secret** off in the app's advanced settings:
|
|
71
|
+
this app does not send `appsecret_proof`.
|
|
72
|
+
3. **System User.** In [Business Settings](https://business.facebook.com/settings) → Users →
|
|
73
|
+
**System Users**, click **Add** and create a System User (role Employee is enough; Admin
|
|
74
|
+
also works). Then, on that System User, click **Add assets**: under **Ad accounts**, pick
|
|
75
|
+
each ad account and allow managing campaigns (needed by the write tools) or only viewing
|
|
76
|
+
performance (reporting only); under **Apps**, pick your app.
|
|
77
|
+
4. **Token.** On the same System User, click **Generate new token**, select your app, and
|
|
78
|
+
permission:
|
|
79
|
+
- `ads_read`: every read tool and reports,
|
|
80
|
+
- `ads_management`: pause, activate, budgets, create,
|
|
81
|
+
- `business_management`: lists ad accounts the business reaches through other portfolios.
|
|
82
|
+
|
|
83
|
+
System User tokens do not expire by default (if an expiry choice is shown, pick
|
|
84
|
+
**Never**). Copy it right away: Meta shows it only once. A reporting-only installation can
|
|
85
|
+
use a token with just `ads_read` (writes then fail with `[FORBIDDEN]`). Meta's guides:
|
|
86
|
+
[System Users](https://developers.facebook.com/docs/marketing-api/system-users),
|
|
87
|
+
[Generate an access token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens#generate-token).
|
|
88
|
+
5. Store it: `agentapps config <alias> META_ACCESS_TOKEN:"<token>"`. In this repo,
|
|
89
|
+
`META_ACCESS_TOKEN=... node packages/create/dist/cli.js health apps/meta-ads` runs the
|
|
90
|
+
health check, which calls `/me` and names the token's owner.
|
|
91
|
+
|
|
92
|
+
Account ids: `list-ad-accounts` returns them as `act_<digits>`; every tool also accepts the
|
|
93
|
+
bare digits.
|
|
94
|
+
|
|
95
|
+
**Access tier and limits.** New apps get the Marketing API's **Limited access** tier: heavily
|
|
96
|
+
rate-limited per ad account and meant for development, with 1 System User. For everyday use,
|
|
97
|
+
request **Full access** with **+Upgrade** on the Marketing API Access Tier feature in the App
|
|
98
|
+
Dashboard once the app qualifies (500 Marketing API calls in the past 15 days, at the time of
|
|
99
|
+
writing); see [Authorization](https://developers.facebook.com/docs/marketing-api/get-started/authorization)
|
|
100
|
+
and [Rate limiting](https://developers.facebook.com/docs/marketing-api/overview/rate-limiting).
|
|
101
|
+
Throttling comes back as `[RATE_LIMITED]`: wait a few minutes. Ad set budgets can change about
|
|
102
|
+
4 times per hour.
|
|
103
|
+
|
|
104
|
+
### Alternative: a personal long-lived token
|
|
105
|
+
|
|
106
|
+
A user access token from the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
|
|
107
|
+
(with the same three permissions), exchanged for a long-lived one, also works, but it expires
|
|
108
|
+
after about 60 days and reaches only the ad accounts that person can use. When it expires,
|
|
109
|
+
calls fail with `[AUTH_REQUIRED]` and you set a new one with the same `agentapps config` line.
|
|
110
|
+
|
|
111
|
+
### Why not OAuth (Facebook Login) in the app
|
|
112
|
+
|
|
113
|
+
The host's generic OAuth flow (authorize URL + code exchange, refresh with a refresh token)
|
|
114
|
+
does not fit Meta today:
|
|
115
|
+
|
|
116
|
+
- Business apps log in with **Facebook Login for Business**, which takes a `config_id` (a
|
|
117
|
+
login configuration created per Meta app) instead of `scope`, plus
|
|
118
|
+
`override_default_response_type=true` for System User tokens. The host builds the authorize
|
|
119
|
+
URL from the manifest's static `authorizeUrl` and `scopes` and the `CLIENT_ID` system secret;
|
|
120
|
+
it has no way to add a per-deployment `config_id`, and the schema requires a non-empty
|
|
121
|
+
`scopes` list that Meta says not to send.
|
|
122
|
+
- With a user-token configuration, Meta returns a short-lived token (hours) and **no refresh
|
|
123
|
+
token**, so the host's refresh never runs. The app would have to exchange it for a 60-day
|
|
124
|
+
token (`fb_exchange_token`, needs the app secret) and a person would still reconnect every
|
|
125
|
+
60 days.
|
|
126
|
+
- Using `ads_read` / `ads_management` on ad accounts of other businesses requires Meta App
|
|
127
|
+
Review (advanced access) and business verification.
|
|
128
|
+
|
|
129
|
+
A System User token pasted once avoids all of this. An OAuth variant would need: `auth.type:
|
|
130
|
+
"oauth2"` with a `facebook` provider (authorize
|
|
131
|
+
`https://www.facebook.com/v26.0/dialog/oauth`, token
|
|
132
|
+
`https://graph.facebook.com/v26.0/oauth/access_token`), only `ACCESS_TOKEN` as user secret,
|
|
133
|
+
system secrets `CLIENT_ID`, `CLIENT_SECRET` and a `CONFIG_ID` set once with
|
|
134
|
+
`agentapps config app.meta-ads CLIENT_ID:<app id>` (and so on), and a host change that adds
|
|
135
|
+
`config_id` and `override_default_response_type` to the authorize URL.
|
|
136
|
+
|
|
137
|
+
Meta also hosts an official Ads MCP server (`https://mcp.facebook.com/ads`). This app differs
|
|
138
|
+
from it by asking for approval before each write, marking spend-affecting tools destructive,
|
|
139
|
+
keeping a small set of bounded tools, and storing one token per installation.
|
|
140
|
+
|
|
141
|
+
## Terms of use
|
|
142
|
+
|
|
143
|
+
Use of the Marketing API is governed by the
|
|
144
|
+
[Meta Platform Terms](https://developers.facebook.com/terms) and the
|
|
145
|
+
[Developer Policies](https://developers.facebook.com/devpolicy/) (including the Marketing API
|
|
146
|
+
section). Ads you create or activate must follow
|
|
147
|
+
[Meta's Advertising Standards](https://transparency.meta.com/policies/ad-standards/), and ads
|
|
148
|
+
about employment, housing, credit, social issues, elections or politics, gambling or financial
|
|
149
|
+
products must declare their special ad category. Graph API versions are supported for about
|
|
150
|
+
two years; this app pins v26.0 (released July 2026).
|
|
151
|
+
|
|
152
|
+
## Logos
|
|
153
|
+
|
|
154
|
+
TODO: no logo shipped yet; `assets/logo.svg` and `assets/logo-mono.svg` are placeholders.
|
|
155
|
+
Searched: the [Meta brand resource center](https://www.meta.com/brand/resources/meta/company-brand/)
|
|
156
|
+
has the official Meta company lockup (four colour variants, including mono), but the download
|
|
157
|
+
sits behind accepting Meta's brand terms, and the page says "All usage of the Meta logo
|
|
158
|
+
requires approval" through Meta's Brand Review process, which a person at the company has to
|
|
159
|
+
request. The meta.com site icon (`static.xx.fbcdn.net`, gradient symbol) is under the same
|
|
160
|
+
terms, and the guidelines say the Meta logo must not stand for Facebook. Icon collections
|
|
161
|
+
(Bootstrap Icons, logo aggregators) are not official sources. Next step: a person accepts the
|
|
162
|
+
terms (or gets Brand Review approval), downloads the lockup zip from the brand page, and adds
|
|
163
|
+
the primary symbol as `assets/logo.svg` and the mono symbol, with fills removed, as
|
|
164
|
+
`assets/logo-mono.svg`.
|
package/agentapp.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"id": "app.meta-ads",
|
|
3
3
|
"name": "Meta Ads",
|
|
4
|
-
"version": "1.0.
|
|
4
|
+
"version": "1.0.1",
|
|
5
5
|
"description": "Meta (Facebook and Instagram) ads through the Marketing API: list ad accounts, campaigns, ad sets, ads and creatives, run performance reports with breakdowns, pause or activate delivery, change budgets, and create campaigns and ad sets (always paused)",
|
|
6
6
|
"tagline": "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
|
|
7
7
|
"author": { "name": "Pablo López Torres", "email": "pablolopeztorres@gmail.com" },
|
package/dist/app.js
CHANGED
|
@@ -21528,7 +21528,7 @@ class AppInstance {
|
|
|
21528
21528
|
success: false,
|
|
21529
21529
|
error: {
|
|
21530
21530
|
code: ErrorCode.UNAUTHORIZED,
|
|
21531
|
-
message: `Missing required
|
|
21531
|
+
message: `Missing required Installation secret(s): ${missingSecrets.join(", ")}. ` + `Configure them for this installation before using ${this.config.id}.`
|
|
21532
21532
|
},
|
|
21533
21533
|
duration: 0
|
|
21534
21534
|
});
|
|
@@ -24360,7 +24360,7 @@ function registerTools(app) {
|
|
|
24360
24360
|
var app = createApp({
|
|
24361
24361
|
id: "app.meta-ads",
|
|
24362
24362
|
name: "Meta Ads",
|
|
24363
|
-
version: "1.0.
|
|
24363
|
+
version: "1.0.1",
|
|
24364
24364
|
description: "Meta (Facebook and Instagram) ads through the Marketing API: list ad accounts, campaigns, ad sets, ads and creatives, run performance reports with breakdowns, pause or activate delivery, change budgets, and create campaigns and ad sets (always paused)",
|
|
24365
24365
|
tagline: "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
|
|
24366
24366
|
author: { name: "Pablo López Torres", email: "pablolopeztorres@gmail.com" },
|
package/package.json
CHANGED
|
@@ -1,11 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agentapps/app.meta-ads",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "Report on Meta ad performance and manage campaigns, ad sets, ads and budgets",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Pablo López Torres <pablolopeztorres@gmail.com>",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"agent-apps",
|
|
9
|
+
"meta",
|
|
10
|
+
"facebook",
|
|
11
|
+
"instagram",
|
|
12
|
+
"ads",
|
|
13
|
+
"advertising",
|
|
14
|
+
"marketing",
|
|
15
|
+
"campaigns",
|
|
16
|
+
"insights",
|
|
17
|
+
"ppc"
|
|
18
|
+
],
|
|
4
19
|
"type": "module",
|
|
5
20
|
"main": "./dist/app.js",
|
|
6
21
|
"exports": {
|
|
7
22
|
".": "./dist/app.js",
|
|
8
23
|
"./agentapp.json": "./agentapp.json",
|
|
9
24
|
"./package.json": "./package.json"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "https://github.com/agentapps/agentapps.git",
|
|
29
|
+
"directory": "apps/meta-ads"
|
|
10
30
|
}
|
|
11
31
|
}
|