用 asc 管理 Apple Ads:OAuth 授权、Campaign 投放与报告全解析
用 asc 管理 Apple Ads:OAuth 授权、Campaign 投放与报告全解析
app-store-connect-cli-skills 是一套基于 asc CLI 的 Agent Skills 技能包,帮你用命令行自动化 App Store 发布全流程。其中 asc-apple-ads 技能专注 Apple Ads 管理:从 OAuth 授权、广告账户发现,到 Campaign 投放与效果报告,全部在终端完成,适合想让广告投放可自动化、可审计的开发者与增长团队。
为什么用 asc 管理 Apple Ads 🚀
和手动在网页控制台点来点去相比,asc ads 子命令有这些优势:
| 痛点 | asc 的解法 |
|---|---|
| OAuth 凭证到处拷贝、CI 难复用 | 凭证以 named profile 持久保存,CI 用环境变量注入 |
| 数据只能截图看报表 | 所有资源与报告命令输出无损 JSON,直接喂给脚本或 jq 分析 |
| 误点按钮导致预算失控 | 高危变更(删除、加预算、调定向)强制 --confirm 确认 |
| 新旧 API 混用易踩坑 | v1 / v5 命令严格分离,迁移路径清晰 |
快速安装技能包
如果你已经在使用 asc,一条命令即可装好全部技能:
asc install-skills
也可以不依赖 asc,直接用 Agent Skills 安装器从仓库安装:
npx skills add rorkai/app-store-connect-cli-skills
更多安装方式(含 Claude Code / Codex 插件市场)见 README.md。
第一步:Apple Ads OAuth 授权与账户绑定
关键认知:Ads 凭证独立于 App Store Connect
Apple Ads 使用独立的 OAuth 凭证,asc auth login(App Store Connect 登录)不会为 Ads 配置任何权限。Ads 凭证要通过 asc ads auth login 单独管理:
asc ads auth login \
--name "Marketing" \
--client-id "$ASC_ADS_CLIENT_ID" \
--team-id "$ASC_ADS_TEAM_ID" \
--key-id "$ASC_ADS_KEY_ID" \
--private-key "$ASC_ADS_PRIVATE_KEY_PATH" \
--ad-account "987654" \
--org "123456"
⚠️ ad account ID 与 org ID 是两套体系:v1 命令用 ad account ID,遗留 v5 命令用 org ID,CLI 严格分开保存,绝不能互相替代。
CI 环境:用环境变量替代钥匙串
CI 上无法使用本机 keychain,设置 Ads 专用变量并显式绕过即可:
export ASC_ADS_CLIENT_ID="SEARCHADS_CLIENT_ID"
export ASC_ADS_TEAM_ID="SEARCHADS_TEAM_ID"
export ASC_ADS_KEY_ID="KEY_ID"
export ASC_ADS_PRIVATE_KEY_PATH="$HOME/.asc/apple-ads-private-key.pem"
export ASC_ADS_AD_ACCOUNT_ID="987654"
export ASC_ADS_BYPASS_KEYCHAIN=1
验证授权并发现广告账户
asc ads auth status --validate --output json
asc ads auth discover --ads-profile "Marketing" --output json
asc ads auth doctor --output json
auth discover 会调用 Platform API v1 的 GET /v1/me 与 GET /v1/acls,列出所有可访问的广告账户、组织与角色。建议人工核对每个账户的 ID、名称、组织与角色后再选用,不要盲选第一条结果。当存在多个 profile 或账户时,后续命令都应显式带上 --ads-profile "Marketing" 和 --ad-account "987654"。
第二步:只读探查,摸清 Campaign 家底 🔍
动任何数据前,先用只读命令验证自己操作的是正确的账户:
asc ads me view --ads-profile "Marketing" --output json
asc ads acls list --ads-profile "Marketing" --output json
asc ads apps search --ads-profile "Marketing" --ad-account "987654" \
--query "Example" --limit 1 --output json
确认无误后,用各资源的 find 子命令盘点家底:
| 盘点目标 | 命令 |
|---|---|
| 广告系列 | asc ads campaigns find |
| 广告组 | asc ads ad-groups find --file query.json |
| 投放的广告 | asc ads ads find --file query.json |
| 投放关键词 | asc ads targeting-keywords find --file query.json |
| 否定关键词 | asc ads negative-keywords find --file query.json |
💡 小贴士:v1 查询的过滤器、排序、分页都写在 JSON 查询文件里(
pagination.offset/pageSize/fetchTotalCount),find类命令没有--paginate标志;v1 过滤器字段用单数value,不要照抄 v5 的conditions/values写法,当前版本会直接拒绝。
第三步:Campaign 投放与受保护变更
创建 Campaign:从"暂停"状态开始最安全
创建 Campaign 可能立即开始花钱。技能推荐的稳妥做法:先建一个显式 status: "PAUSED" 的 Campaign,验证无误后再恢复投放。CampaignCreate 载荷必须包含 adAccountId、billingEvent、dailyBudget、name、promotedObjectId、promotedObjectType、targeting 字段。
asc ads campaigns create --ads-profile "Marketing" \
--ad-account "987654" --file paused-campaign.json
⚠️ CLI 会原样发送 JSON 文件:
--ad-account只决定请求上下文,不会替你往载荷里注入adAccountId,字段一个都不能漏。
暂停、恢复与删除
asc ads campaigns pause --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id"
asc ads campaigns resume --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --confirm
asc ads campaigns delete --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --confirm
变更安全分级一览
| 操作类型 | 是否要求 --confirm |
|---|---|
| 显式 PAUSED 的 Campaign 创建 | 否(唯一的安全例外) |
| 仅改名 / 改名 + 置为 PAUSED | 否 |
| 恢复投放、调整预算、定向、出价、日期 | 是 |
| 删除、批量创建/更新、应用建议 | 是 |
共享预算 budget-orders 增删改 |
是 |
第四步:报告与优化建议 📊
拉取 Campaign 报告
报告请求体是端点专属的 JSON:日期区间写在 timeRange 下,分页用 offset / pageSize,Campaign ID 写在 filters 里:
{
"pagination": {"offset": 0, "pageSize": 20},
"filters": [
{"field": "campaignId", "operator": "EQUALS", "value": ["campaign-id"]}
],
"groupBy": ["countryOrRegion"],
"timeRange": {
"start": "2026-08-01", "end": "2026-08-14",
"timeZone": "ORTZ", "granularity": "DAILY"
}
}
asc ads reports apps campaigns --ads-profile "Marketing" \
--ad-account "987654" --file report.json --output json
不同报告实体接受的 groupBy 值不同,执行前用对应叶子命令的 --help 确认。
应用优化建议
Apple Ads 会给出预算等优化建议。查看建议没有风险,但应用或忽略建议可能改变花费,必须加 --confirm:
asc ads recommendations daily-budgets find --ads-profile "Marketing" \
--ad-account "987654" --file query.json
asc ads recommendations daily-budgets apply --ads-profile "Marketing" \
--ad-account "987654" --file recommendations.json --confirm
v5 → v1 迁移:旧命令对照表 🔄
已弃用的 Campaign Management API v5 命令位于 asc ads v5 ... 下,Apple 将于 2027 年 1 月 26 日 正式下线 v5。迁移原则是逐条命令替换:每个脚本先有审核过的 v1 请求体和响应解析器,再切过去。
| 已弃用 v5 命令 | Platform API v1 对应 |
|---|---|
asc ads v5 campaigns list |
asc ads campaigns find |
asc ads v5 apps localized-details |
asc ads apps locales find |
asc ads v5 product-pages list |
asc ads product-pages find |
asc ads v5 reports campaigns |
asc ads reports apps campaigns |
asc ads v5 campaigns pause / resume |
asc ads campaigns pause / resume |
注意:v1 与 v5 的载荷和响应结构不同,CLI 不会替你翻译。有 7 个 v5 叶子命令没有一对一的 v1 替代(如 product-page countries/devices、部分批量删除、impression-share 报告等),迁移时需要单独设计替代方案。
实战安全检查清单 ✅
- 用
auth discover+ 一次单结果 app search 证明操作的是正确账户 - 测试 Campaign 使用唯一时间戳命名 + 显式
PAUSED状态 - 把测试中创建的每个 ID 从 JSON 输出里保存下来
- 任何操作前,先暂停可能产生花费的资源
- 只删除测试自己创建的 Campaign,再复查一次确认已清理
参考资料
- skills/asc-apple-ads/SKILL.md — Apple Ads 完整操作指南
- skills/asc-cli-usage/SKILL.md — asc 命令规范、标志约定与输出格式
- README.md — 技能全览与安装方式