@agentapps/app.tiktok-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 +127 -2
- package/agentapp.json +42 -0
- package/dist/app.js +23981 -0
- package/package.json +28 -4
package/README.md
CHANGED
|
@@ -1,3 +1,128 @@
|
|
|
1
|
-
#
|
|
1
|
+
# TikTok Ads
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Lets an agent work with TikTok ad accounts through the TikTok API for Business (Marketing API
|
|
4
|
+
v1.3, `https://business-api.tiktok.com/open_api/v1.3`). It can list the ad accounts a token can
|
|
5
|
+
reach, list campaigns, ad groups and ads, and run performance and audience reports. It can also
|
|
6
|
+
pause or enable delivery and change a campaign or ad group budget. It does not create or delete
|
|
7
|
+
anything. Enabling delivery and budget changes affect spend: they are marked destructive and ask
|
|
8
|
+
for approval.
|
|
9
|
+
|
|
10
|
+
## Tools
|
|
11
|
+
|
|
12
|
+
| Tool | What it does | Writes? |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `list-advertisers` | The ad accounts (advertisers) the access token is authorized for. Needs the app credentials (system secrets). | no |
|
|
15
|
+
| `get-advertiser-info` | Account details: status, currency, time zone, balance, company, country (up to 100 accounts). | no |
|
|
16
|
+
| `list-campaigns` | Campaigns of one account with status, budget and budget mode; filters by id, name and status; paged. | no |
|
|
17
|
+
| `list-ad-groups` | Ad groups, optionally of some campaigns, with status, budget, bidding and schedule; paged. | no |
|
|
18
|
+
| `list-ads` | Ads, optionally of some campaigns or ad groups, with status, format, text and landing page; paged. | no |
|
|
19
|
+
| `get-report` | Synchronous report (`report/integrated/get`): BASIC or AUDIENCE, any level, dimensions, metrics, date range or lifetime, filters, totals. Returns columns and rows. | no |
|
|
20
|
+
| `pause-delivery` | Pauses up to 20 campaigns, ad groups or ads (reversible). | yes, sensitive |
|
|
21
|
+
| `enable-delivery` | Enables up to 20 campaigns, ad groups or ads. **Affects spend.** | yes, sensitive, destructive |
|
|
22
|
+
| `update-budget` | Sets one campaign or ad group budget; returns the previous budget so it can be reverted. **Affects spend.** | yes, sensitive, destructive |
|
|
23
|
+
|
|
24
|
+
Limits:
|
|
25
|
+
|
|
26
|
+
- Lists return at most 100 items per page, reports at most 500 rows per page, and every result
|
|
27
|
+
stays under 50,000 characters (`limitApplied` on lists, a `[RESULT_TOO_LARGE]` error naming
|
|
28
|
+
what to shrink on reports).
|
|
29
|
+
- Report date ranges are at most 365 days. TikTok applies stricter limits of its own (for
|
|
30
|
+
example on hourly data) and says so in a `[BAD_REQUEST]` error.
|
|
31
|
+
- Report dates and `stat_time_*` values are in the ad account's time zone; money is in the
|
|
32
|
+
account currency (see `get-advertiser-info`).
|
|
33
|
+
|
|
34
|
+
### TikTok ids and the CLI
|
|
35
|
+
|
|
36
|
+
TikTok ids (advertiser, campaign, ad group, ad) are 16-19 digit numbers, above JavaScript's
|
|
37
|
+
safe integer range. The `agentapps` CLI turns `key:value` arguments that look like numbers into
|
|
38
|
+
numbers, which would round such an id to a different one. The tools refuse a rounded id, so pass
|
|
39
|
+
ids inside a single JSON object (or as JSON on stdin):
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
agentapps tiktok-ads tool list-campaigns '{"advertiserId":"7012345678901234567"}'
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
MCP clients send JSON, so this only matters on the command line.
|
|
46
|
+
|
|
47
|
+
## Setup
|
|
48
|
+
|
|
49
|
+
The app needs three values: the TikTok developer app's id and secret (system secrets, shared by
|
|
50
|
+
every installation) and an advertiser access token (a user secret, per installation).
|
|
51
|
+
|
|
52
|
+
1. **Developer account and app.** Sign in at the
|
|
53
|
+
[TikTok API for Business portal](https://business-api.tiktok.com/portal) with a TikTok for
|
|
54
|
+
Business account, register as a developer and create an app (My Apps, Create). Give it an
|
|
55
|
+
advertiser redirect URL you control and request the Marketing API permission scopes this app
|
|
56
|
+
uses: **Ad Account Management** (account list and info), **Ads Management** (campaigns, ad
|
|
57
|
+
groups, ads, status and budget changes) and **Reporting**. TikTok reviews new apps; once it is
|
|
58
|
+
approved, the app page shows the **App ID**, the **Secret** and an **advertiser authorization
|
|
59
|
+
URL**.
|
|
60
|
+
2. **Authorize the ad accounts.** Open the advertiser authorization URL while signed in as a
|
|
61
|
+
user with access to the ad accounts (or the Business Center that owns them), pick the
|
|
62
|
+
accounts and confirm. TikTok redirects to your redirect URL with an `auth_code` query
|
|
63
|
+
parameter, valid for a short time.
|
|
64
|
+
3. **Exchange the code for a long-lived access token** (once, by hand):
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
curl -s -X POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/ \
|
|
68
|
+
-H 'Content-Type: application/json' \
|
|
69
|
+
-d '{"app_id":"<App ID>","secret":"<Secret>","auth_code":"<auth_code>"}'
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The answer's `data.access_token` is the token, and `data.advertiser_ids` lists the accounts it
|
|
73
|
+
can manage. TikTok issues advertiser tokens as long-term tokens with no refresh step; one
|
|
74
|
+
stops working when the advertiser revokes the authorization, and the tools then answer
|
|
75
|
+
`[AUTH_REQUIRED]`. To add accounts later, authorize again and use the new token.
|
|
76
|
+
4. **Install and configure:**
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
agentapps install app.tiktok-ads tiktok-ads
|
|
80
|
+
# System secrets: set on the app id, shared by every installation
|
|
81
|
+
agentapps config app.tiktok-ads TIKTOK_APP_ID:"<App ID>"
|
|
82
|
+
agentapps config app.tiktok-ads TIKTOK_APP_SECRET:"<Secret>"
|
|
83
|
+
# User secret: set on the installed alias
|
|
84
|
+
agentapps config tiktok-ads TIKTOK_ACCESS_TOKEN:"<access_token>"
|
|
85
|
+
agentapps tiktok-ads tools
|
|
86
|
+
agentapps tiktok-ads tool list-advertisers
|
|
87
|
+
agentapps tiktok-ads tool get-report '{"advertiserId":"<id>","startDate":"2026-10-01","endDate":"2026-10-07","dimensions":["campaign_id","stat_time_day"]}'
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- `TIKTOK_ACCESS_TOKEN` (user secret, required): the advertiser access token from step 3. Every
|
|
91
|
+
tool needs it.
|
|
92
|
+
- `TIKTOK_APP_ID`, `TIKTOK_APP_SECRET` (system secrets): only `list-advertisers` and the health
|
|
93
|
+
check use them, because TikTok's advertiser list endpoint asks for the app credentials next to
|
|
94
|
+
the token. Without them the other tools still work with an advertiser id you already know (from
|
|
95
|
+
step 3 or TikTok Ads Manager), and the health check reports `degraded`.
|
|
96
|
+
|
|
97
|
+
### Why not the host's OAuth flow
|
|
98
|
+
|
|
99
|
+
TikTok's authorization does not follow the standard OAuth 2.0 shape the host implements: the
|
|
100
|
+
authorize URL takes `app_id` instead of `client_id`, the callback carries `auth_code`, the token
|
|
101
|
+
exchange is a JSON body (`app_id`, `secret`, `auth_code`) instead of a form post, and the token
|
|
102
|
+
comes back inside TikTok's `{ code, message, data }` envelope instead of a top-level
|
|
103
|
+
`access_token`. Since the advertiser token is long-term, a one-time manual exchange is enough.
|
|
104
|
+
|
|
105
|
+
## Terms of use
|
|
106
|
+
|
|
107
|
+
Using the API requires a TikTok for Business developer account and accepting the TikTok For
|
|
108
|
+
Business Developer Terms when registering in the
|
|
109
|
+
[API for Business portal](https://business-api.tiktok.com/portal), on top of the TikTok
|
|
110
|
+
Advertising Terms that govern the ad accounts. See TikTok's
|
|
111
|
+
[About API for Business](https://ads.tiktok.com/help/article/marketing-api) help article. The API
|
|
112
|
+
is rate limited per app and advertiser; when TikTok answers with code 40100 the tools return a
|
|
113
|
+
`[RATE_LIMITED]` error and the agent should wait before retrying.
|
|
114
|
+
|
|
115
|
+
## Logos
|
|
116
|
+
|
|
117
|
+
| File | Source | Changes |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| assets/logo.png | TikTok for Developers logo pack, linked from the [design guidelines](https://developers.tiktok.com/doc/getting-started-design-guidelines) (`logo-pack.zip`), `TikTok Logo Pack/TikTok – Icons/TikTok_Icon_Black_Square.png` (1200x1200) | none (renamed) |
|
|
120
|
+
|
|
121
|
+
TODO: no official one-colour SVG found yet for `assets/logo-mono.svg`. Searched: the TikTok for
|
|
122
|
+
Developers logo pack above (SVGs only for the "Continue with TikTok" buttons, which contain text;
|
|
123
|
+
the icon itself is PNG and Adobe Illustrator only), the
|
|
124
|
+
[TikTok Brand Hub](https://tiktokbrandhub.com/) linked from the developer site (pages rendered
|
|
125
|
+
by JavaScript with no downloadable files; its favicon SVG is the note on a coloured square
|
|
126
|
+
badge, which leaves a solid block once the fills are removed), the TikTok for Developers site
|
|
127
|
+
header (a multi-colour layered "TikTok for Developers" wordmark), and the tiktok.com and
|
|
128
|
+
TikTok for Business home pages (no SVG logo in the served HTML).
|
package/agentapp.json
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "app.tiktok-ads",
|
|
3
|
+
"name": "TikTok Ads",
|
|
4
|
+
"version": "1.0.1",
|
|
5
|
+
"description": "TikTok Ads through the TikTok API for Business (Marketing API v1.3): list ad accounts, campaigns, ad groups and ads, run performance and audience reports, pause or enable delivery and change campaign or ad group budgets. Enabling delivery and budget changes affect spend and ask for approval.",
|
|
6
|
+
"tagline": "Report on TikTok ad campaigns and pause, enable or re-budget them",
|
|
7
|
+
"author": { "name": "Pablo López Torres", "email": "pablolopeztorres@gmail.com" },
|
|
8
|
+
"license": "MIT",
|
|
9
|
+
"logo": "assets/logo.png",
|
|
10
|
+
"logoMono": "assets/logo-mono.svg",
|
|
11
|
+
"terms": "https://agentapps.tech/terms",
|
|
12
|
+
"category": "marketing",
|
|
13
|
+
"keywords": [
|
|
14
|
+
"tiktok",
|
|
15
|
+
"tiktok-ads",
|
|
16
|
+
"ads",
|
|
17
|
+
"advertising",
|
|
18
|
+
"marketing",
|
|
19
|
+
"campaigns",
|
|
20
|
+
"reports",
|
|
21
|
+
"ppc"
|
|
22
|
+
],
|
|
23
|
+
"entrypoint": {
|
|
24
|
+
"type": "module",
|
|
25
|
+
"path": "src/app.ts",
|
|
26
|
+
"export": "factory"
|
|
27
|
+
},
|
|
28
|
+
"runtime": {
|
|
29
|
+
"transport": "stdio",
|
|
30
|
+
"command": "tsx",
|
|
31
|
+
"args": ["src/app.ts"]
|
|
32
|
+
},
|
|
33
|
+
"capabilities": {
|
|
34
|
+
"tools": true,
|
|
35
|
+
"health": true
|
|
36
|
+
},
|
|
37
|
+
"auth": {
|
|
38
|
+
"type": "api-key",
|
|
39
|
+
"systemSecrets": ["TIKTOK_APP_ID", "TIKTOK_APP_SECRET"],
|
|
40
|
+
"installationSecrets": ["TIKTOK_ACCESS_TOKEN"]
|
|
41
|
+
}
|
|
42
|
+
}
|