用 asc 管理 Apple Ads:OAuth 授权、Campaign 投放与报告全解析

原创2026-10-15 20:42:511,368 阅读

用 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,再复查一次确认已清理

参考资料

登录后查看全文
app-store-connect-cli-skills