asc-new-app-release

首次发布到 App Store

此工作流会将一个全新的应用从零开始推进到提交至 App Store。它会处理常规发布工作流（asc-release-workflow）不会处理的所有事项——仅在首次提交时进行的一次性设置。

开始之前

向用户收集以下信息（或从项目中获取）：

信息	查找位置	示例
Bundle ID	Xcode 项目或 .xcconfig	com.mycompany.myapp
应用名称	用户希望在 App Store 上使用的名称	My Cool App
平台	iOS、macOS 或两者	ios
类别	参见类别参考	EDUCATION
描述	由用户提供或由你起草	功能列表段落
支持 URL	GitHub 仓库、网站等	https://github.com/...
定价	免费或付费	免费
SKU	唯一字符串（如未提供则生成）	myapp-ios-2026

工作流概览

Phase 1: Identity        → Bundle ID + App creation
Phase 2: Metadata        → Category, description, keywords, URLs
Phase 3: Compliance      → Age rating, pricing, privacy labels, review contact
Phase 4: Build           → Archive, upload, link to version
Phase 5: Readiness       → Check all requirements, fix gaps
Phase 6: Submit          → Submit for App Review

---

阶段 1：身份信息

步骤 1.1：注册 Bundle ID

检查 Bundle ID 是否已存在：

asc bundle-ids list

如果不存在，则注册：

asc bundle-ids create \
  --name "<APP_NAME>" \
  --identifier "<BUNDLE_ID>" \
  --platform IOS   # or UNIVERSAL for iOS + macOS

步骤 1.2：在 App Store Connect 上创建应用

使用 iris API（通过 Web 会话访问的私有 API），因为它可以通过一次调用创建应用、版本和本地化信息：

asc iris apps create \
  --name "<APP_NAME>" \
  --bundle-id "<BUNDLE_ID>" \
  --sku "<SKU>"

保存返回的 App ID——后续每条命令都会用到它。

如果名称已被占用（返回带有 DUPLICATE.DIFFERENT_ACCOUNT 的 409 错误），请让用户提供其他名称。常见的解决办法：添加“App”、“Studio”、“AI”或其他有辨识度的词。

如果 iris 不可用（没有 Web 会话），则改用 REST API：

# This requires the bundle ID to already be registered
asc apps create \
  --name "<APP_NAME>" \
  --bundle-id-id "<BUNDLE_ID_RESOURCE_ID>" \
  --sku "<SKU>" \
  --primary-locale "en-US"

步骤 1.3：验证应用并获取 ID

# Get app info ID (needed for categories, localizations)
asc app-infos list --app-id <APP_ID>
# Save: APP_INFO_ID

# Get version ID (needed for screenshots, build linking)
asc versions list --app-id <APP_ID>
# Save: VERSION_ID (the one in PREPARE_FOR_SUBMISSION state)

# Get version localization ID (needed for description, keywords)
asc version-localizations list --version-id <VERSION_ID>
# Save: LOCALIZATION_ID

---

阶段 2：元数据

步骤 2.1：设置类别

询问用户最适合的类别。完整列表请参见类别参考。

asc app-infos update \
  --app-info-id <APP_INFO_ID> \
  --primary-category <CATEGORY>

常见类别：EDUCATION、DEVELOPER_TOOLS、PRODUCTIVITY、UTILITIES、BUSINESS、ENTERTAINMENT、PHOTO_AND_VIDEO。

步骤 2.2：设置版本元数据

填写描述、关键词和 URL：

asc version-localizations update \
  --localization-id <LOCALIZATION_ID> \
  --description "<DESCRIPTION>" \
  --keywords "<COMMA_SEPARATED_KEYWORDS>" \
  --support-url "<SUPPORT_URL>" \
  --marketing-url "<MARKETING_URL>"

描述提示：

• 第一行是吸引用户的亮点——要写得引人入胜
• 用项目符号列出 5-7 项主要功能（使用 •）
• 控制在 4000 个字符以内
• 不要包含定价信息或竞品名称

关键词提示：

• 总长度最多 100 个字符，以逗号分隔
• 不要重复应用名称（它已经会被索引）
• 使用单数形式（例如使用“photo”，而不是“photos”）
• 以 8-12 个关键词为宜

注意： 首个版本不要设置 --whats-new——Apple 不允许这样做。该字段仅用于更新。

步骤 2.3：设置应用级元数据（可选）

副标题和隐私政策 URL 设置在应用信息的本地化内容中（而非版本中）：

# List app info localizations
asc app-info-localizations list --app-info-id <APP_INFO_ID>
# Save: APP_INFO_LOC_ID

# Update subtitle and privacy URL
asc app-info-localizations update \
  --localization-id <APP_INFO_LOC_ID> \
  --subtitle "<SHORT_SUBTITLE>" \
  --privacy-policy-url "<PRIVACY_POLICY_URL>"

---

阶段 3：合规性

步骤 3.1：年龄分级

默认年龄分级（NONE = 4+）通常适用于工具类/效率类应用。请确认：

asc age-rating get --app-info-id <APP_INFO_ID>

如果应用包含成熟内容，请更新分级：

asc age-rating update --declaration-id <APP_INFO_ID> \
  --age-rating-override SEVENTEEN_PLUS

步骤 3.2：定价、可用性和内容权利

应用设置好价格之前，提交会被拒绝；新应用也无法在设置好可用性之前于任何地区销售。询问用户定价（如果应用通过 App 内购买或订阅获得收入，通常选择免费），以及销售地区（通常选择所有地区）。

# Price: pick a point in the base territory; Apple equalizes the rest. customerPrice 0.0 = Free.
FREE=$(asc apps price-points list --app-id <APP_ID> | jq -r '.data[] | select(.customerPrice == "0.0") | .id')
asc apps prices set --app-id <APP_ID> --base-territory USA --price-point-id "$FREE"

# Availability (App Store Connect's "Set Up Availability")
asc app-availability create --app-id <APP_ID> --all-territories --available-in-new-territories

# Content rights — a legal declaration, so ask the user which is true
asc apps update --app-id <APP_ID> --content-rights-declaration DOES_NOT_USE_THIRD_PARTY_CONTENT   # or USES_THIRD_PARTY_CONTENT

发布前，所有地区均显示 CANNOT_SELL + AVAILABLE_FOR_SALE_UNRELEASED_APP；这是预期情况。

步骤 3.3：审核联系信息

asc version-review-detail update \
  --version-id <VERSION_ID> \
  --contact-email "<EMAIL>" \
  --contact-phone "<PHONE>"

向用户询问联系邮箱和电话号码。App Review 需要这些信息，以便在有疑问时联系用户。

步骤 3.4：隐私营养标签

App 隐私问答没有公开的 App Store Connect API，只能在 App Store Connect 网页中发布（或通过网页会话发布）。发布前，提交会因“您必须已发布有关 App 数据使用情况的问答”而被拒绝。

如果 App 不会收集任何用户数据，请告知用户：App Store Connect > App > App 隐私 > 开始使用 >“否，我们不会收集此 App 的数据”> 发布。

如果 App 会收集数据，请逐一确认每种数据类型。类别请参阅 Apple 隐私文档。

---

阶段 4：构建

步骤 4.1：归档并上传

# Get the next build number
BUILD_NUMBER=$(asc builds next-number \
  --app-id <APP_ID> \
  --version <VERSION_STRING> \
  --platform <PLATFORM>)

# Archive + upload in one step
asc builds archive \
  --scheme <SCHEME> \
  --platform <PLATFORM> \
  --signing-style automatic \
  --team-id <TEAM_ID> \
  --upload \
  --app-id <APP_ID> \
  --version <VERSION_STRING> \
  --build-number "$BUILD_NUMBER"

如果用户已经有 IPA/PKG：

asc builds upload \
  --app-id <APP_ID> \
  --file <PATH_TO_IPA> \
  --version <VERSION_STRING> \
  --build-number "$BUILD_NUMBER" \
  --wait

步骤 4.2：等待处理

asc builds uploads get --upload-id <UPLOAD_ID>

轮询，直到 state 为 COMPLETE。常见失败原因：

• 缺少图标 → 修复资源目录
• 缺少权利 → macOS 需要 App Sandbox
• CFBundleVersion 不匹配 → 二进制文件中的构建号必须匹配

步骤 4.3：将构建版本关联到版本

# Find the build (match by build number)
asc builds list --app-id <APP_ID>

# Link to the version
asc versions set-build \
  --version-id <VERSION_ID> \
  --build-id <BUILD_ID>

---

阶段 5：就绪情况检查

asc versions check-readiness --version-id <VERSION_ID>

仔细检查输出。首次提交的 App 常见的缺失项：

检查项	可能的状态	修复方法
stateCheck	通过	应为 PREPARE_FOR_SUBMISSION
buildCheck	尚未上传时失败	上传并关联一个构建版本（阶段 4）
pricingCheck	失败	asc apps prices set（步骤 3.2）
reviewContactCheck	失败	asc version-review-detail update（步骤 3.3）
localizationCheck	缺少屏幕截图时失败	上传屏幕截图
screenshotSetCount: 0	失败	每种设备至少需要一个屏幕截图集

屏幕截图

首次提交必须提供屏幕截图。如果用户有屏幕截图技能或自动化工具：

# Create screenshot set for a device
asc screenshot-sets create \
  --localization-id <LOCALIZATION_ID> \
  --display-type APP_IPHONE_67

# Upload screenshot
asc screenshots create \
  --screenshot-set-id <SET_ID> \
  --file <PATH_TO_SCREENSHOT>

所需的显示类型取决于平台。iOS 至少需要：

• APP_IPHONE_67（6.7" — iPhone Pro Max）
• APP_IPHONE_61（6.1" — iPhone Pro）— 可由 6.7" 的屏幕截图生成

macOS：APP_DESKTOP

---

阶段 6：提交

当 isReadyToSubmit 为 true 时：

新 App 的 App 内购买项目和订阅属于首次上架产品，因此必须随此版本一并送审。先预览并与用户确认，然后提交：

asc versions submit --version-id <VERSION_ID> --with-products --dry-run --output table
asc versions submit --version-id <VERSION_ID> --with-products

检查试运行列表中是否包含用户预期的所有产品——仍处于 MISSING_METADATA 状态的产品不会包含在内。如果 Apple 拒绝提交，错误信息会列出每个原因（缺少设备屏幕截图、内容权利、App 隐私问答、定价）；请参阅 submit-with-products.md。

告知用户：“您的 App 已提交审核！Apple 通常会在 24-48 小时内完成审核。获批（或有问题需要处理）时，您会收到电子邮件通知。”

---

快速参考：完整命令序列

适用于不收集数据的免费 iOS App：

# 1. Register bundle ID
asc bundle-ids create --name "My App" --identifier "com.me.myapp" --platform IOS

# 2. Create app
asc iris apps create --name "My App" --bundle-id "com.me.myapp" --sku "myapp-2026"
# → APP_ID

# 3. Get IDs
asc app-infos list --app-id $APP_ID           # → APP_INFO_ID
asc versions list --app-id $APP_ID             # → VERSION_ID
asc version-localizations list --version-id $VERSION_ID  # → LOC_ID

# 4. Category
asc app-infos update --app-info-id $APP_INFO_ID --primary-category EDUCATION

# 5. Description + keywords
asc version-localizations update --localization-id $LOC_ID \
  --description "..." --keywords "..." --support-url "..." --marketing-url "..."

# 5b. Price (free), availability, content rights — App Privacy is published in the web UI
FREE=$(asc apps price-points list --app-id $APP_ID | jq -r '.data[] | select(.customerPrice == "0.0") | .id')
asc apps prices set --app-id $APP_ID --base-territory USA --price-point-id "$FREE"
asc app-availability create --app-id $APP_ID --all-territories --available-in-new-territories
asc apps update --app-id $APP_ID --content-rights-declaration DOES_NOT_USE_THIRD_PARTY_CONTENT

# 6. Review contact
asc version-review-detail update --version-id $VERSION_ID \
  --contact-email "[email protected]" --contact-phone "+1-555-0100"

# 7. Archive + upload
BUILD=$(asc builds next-number --app-id $APP_ID --version 1.0 --platform IOS)
asc builds archive --scheme MyApp --platform ios --signing-style automatic \
  --team-id XXXXXXXXXX --upload --app-id $APP_ID --version 1.0 --build-number $BUILD

# 8. Link build
asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID

# 9. Check readiness
asc versions check-readiness --version-id $VERSION_ID

# 10. Submit, with any in-app purchases and subscriptions (first-time products)
asc versions submit --version-id $VERSION_ID --with-products --dry-run
asc versions submit --version-id $VERSION_ID --with-products