Automate your development process with the App Store Connect API
App Store, Distribution & Marketing 进阶 1m

用 App Store Connect API 自动化你的开发流程

Automate your development process with the App Store Connect API

2025年6月9日

在 Apple 官方观看视频

一句话判断

等了好几年，App Store Connect 终于有了 Webhook 和 Build Upload API——CI/CD 里最缺失的那一环现在补上了。

这场 Session 讲了什么

Dajinsol Jeon 从典型的 app 开发循环讲起：上传 build -> 分发给 tester -> 收反馈 -> 修 bug -> 再上传。核心问题是：这个循环跑得越快越好，但以前很多环节需要手动操作或轮询。

今年三个重磅 API 更新：

1. Webhook API

  • 告别轮询。App Store Connect 会在事件发生时主动 POST 到你的 webhook listener。
  • 支持的事件类型：Build Upload State、Build Beta State、TestFlight Feedback、App Version State、Apple-Hosted Background Asset State。
  • 注册方式：ASC 网站 UI 或 API（POST /v1/webhooks）。
  • 安全验证：HMAC-SHA256 签名，secret 由你设置，通过 X-Apple-SIGNATURE header 校验。

2. Build Upload API

  • 终于可以通过 API 上传 build，不再只能依赖 Xcode 或 Transporter。
  • 流程：创建 BuildUpload -> 创建 BuildUploadFile（文件名、大小、asset type）-> 获取 upload instructions（URL、method、headers）-> 上传二进制 -> PATCH 标记完成。
  • 大文件自动拆分为多个 chunk，每个 chunk 有独立的 upload operation。
  • 上传完成后触发 Webhook，收到 state 从 PROCESSING 变为 COMPLETE 的通知。

3. Feedback API

  • 可以通过 API 获取 TestFlight 的 screenshot feedback 和 crash feedback。
  • 新 feedback 提交时触发 Webhook，拿到 feedback ID 后调 API 获取详情（设备信息、截图 URL、crash log）。
  • 截图和 crash log 可以通过单独的 endpoint 下载。

值得深挖的点

Build Upload 的分块策略：API 会根据文件大小返回多个 upload operation，每个 operation 有不同的 URL 和 byte range。这不是可选的优化，而是大文件必须走这个路径。如果你的 CI 脚本没处理多 chunk，大项目会直接失败。

Webhook 的幂等性设计：Webhook 可能重复送达（网络抖动、重试），你的 listener 必须做幂等处理。建议用 event ID + 状态机来管理，不要单纯依赖 webhook payload 的 state 字段。

从「轮询」到「事件驱动」的架构转变：以前很多人用 fastlane + cron 定期检查 build 状态。现在 webhook 让你可以做到真正的事件驱动：build 上传完成 -> 自动触发 TestFlight 分发 -> feedback 到来 -> 自动创建 Jira ticket。整个循环可以零人工介入。

代码片段

# 注册 Webhook
curl -X POST https://api.appstoreconnect.apple.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": {
      "type": "webhooks",
      "attributes": {
        "url": "https://your-server.com/webhooks",
        "secret": "your-secret-key",
        "eventTypes": ["BUILD_UPLOAD_STATE", "TESTFLIGHT_FEEDBACK"]
      }
    }
  }'

# 创建 BuildUpload
curl -X POST https://api.appstoreconnect.apple.com/v1/buildUploads \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": {
      "type": "buildUploads",
      "attributes": {
        "bundleVersion": "42",
        "platform": "IOS"
      }
    }
  }'

# 验证 Webhook 签名（伪代码）
const crypto = require('crypto');
const signature = req.headers['x-apple-signature'];
const expected = crypto.createHmac('sha256', secret)
  .update(req.body)
  .digest('hex');
if (signature !== expected) return res.status(401).send('Invalid signature');

最佳实践

  1. Webhook listener 先返回 200，再异步处理：ASC 期望在合理时间内收到响应。先把 payload 存下来（Redis/DB），再异步消费，避免超时导致重试。
  2. Build Upload 要处理 chunk：不要假设只有一个 upload operation。遍历返回的 operations 数组，按 byte range 分片上传。
  3. Webhook + API 双保险：Webhook 通知你事件发生了，但 payload 信息最少化（只有 ID 和类型）。收到后立即调 API 拿完整数据，不要只依赖 webhook payload 做决策。
  4. Feedback API 配合 digest 通知：328 session 提到了 App Store Connect app 的 feedback digest 功能。API 和 digest 搭配用：API 做自动化处理，digest 做人工 review。
  5. Sandbox 环境也要测 webhook：开发阶段在 sandbox 环境注册 webhook，模拟 build 上传流程，验证整个 pipeline。

还有什么值得关注

  • Apple-Hosted Background Assets 也有对应的 API 和 Webhook，适合管理 200GB 以内的资源包。
  • App Version State webhook 可以追踪你的 app 从「等待审核」到「上架」的全流程。
  • 这些 API 全部是 RESTful 标准接口，可以用任何语言集成，不依赖 fastlane 或任何特定工具链。
  • 配合观看 “What’s new in App Store Connect”（328）了解完整的 ASC 更新。
App Store, Distribution & Marketing