asc-in-app-events

asc 应用内活动

仅对请求的阶段使用 asc app-events。本地化、媒体上传或诊断请求并不授权创建或提交其他活动。 保留已解析的应用、活动、平台、语言区域和现有授权。

检查目标

执行前检查 asc app-events --help 和相关子命令的帮助信息。 解析应用 ID 和认证配置；更改现有活动前先检查该活动：

asc app-events list --app "APP_ID" --paginate --output json
asc app-events view --event-id "EVENT_ID" --output json
asc app-events localizations list --event-id "EVENT_ID" --paginate --output json

解析结果时使用显式的 --output json；输出默认值会根据 TTY 状态调整。 区分活动 ID 和本地化 ID。

准备并创建

• 选择活动徽章和目标地区。检查帮助信息，确认支持的 --event-type、--purpose 和 --purchase-requirement 值；不要推断 App Store Connect 中描述的所有值都受 CLI 支持。
• 设置未来的 RFC 3339 日期：开始时间早于结束时间，持续时间为 15 分钟至 31 天， 发布开始时间最早不得早于活动开始时间 14 天，且不得晚于活动开始时间。 CLI 会解析时间戳，但不会强制执行 Apple 的所有排期规则。
• 提供可打开活动目标页面的深层链接。在目标应用版本中测试通用链接或自定义 URL 方案； 仅注册方案并不能证明目标页面可正常打开。即使未提供深层链接也可能成功创建活动， 但该活动尚未准备好接受审核。

创建前，将日期变量替换为已确认的日程：

asc app-events create \
  --app "APP_ID" --name "Summer Challenge" --event-type CHALLENGE \
  --start "$START_RFC3339" --end "$END_RFC3339" \
  --publish-start "$PUBLISH_START_RFC3339" \
  --deep-link "myapp://event/summer" --primary-locale en-US \
  --purchase-requirement NO_COST_ASSOCIATED \
  --priority NORMAL --purpose APPROPRIATE_FOR_ALL_USERS --output json

--name 是内部引用名称，最多 64 个字符。保留返回的活动 ID。对于现有活动， 使用 asc app-events update，而不要创建替代活动；检查其帮助信息，确认要更改的字段。

本地化并上传媒体

仅创建缺失且已请求的本地化内容。显示名称最多 30 个字符， 简短描述最多 50 个字符，长描述最多 120 个字符。对于现有本地化内容， 使用 asc app-events localizations update --localization-id "LOC_ID"，并提供需要更改的文本标志。

asc app-events localizations create \
  --event-id "EVENT_ID" --locale en-US --name "Summer Challenge" \
  --short-description "Win three duels a day." \
  --long-description "Play every day during the challenge to earn the summer badge."

asc app-events screenshots create \
  --event-id "EVENT_ID" --locale en-US \
  --path "./event-card.png" --asset-type EVENT_CARD
asc app-events screenshots create \
  --event-id "EVENT_ID" --locale en-US \
  --path "./event-details.png" --asset-type EVENT_DETAILS_PAGE

如果本地化 ID 已解析，请使用 --localization-id "LOC_ID"，而不要同时使用 --event-id 和 --locale。视频上传使用 asc app-events video-clips create；检查其帮助信息，了解素材类型和 --preview-frame-time-code。

要重复使用现有的 Asset Library 媒体，请将活动本地化 ID 与 EVENT_CARD_ASSET 或 EVENT_DETAILS_PAGE_ASSET 一起用于 asc app-events localizations placements。 按照 Asset Library 工作流 进行上传、交付和放置检查；放置媒体并不会提交活动。

使用 JPG/JPEG/PNG 图片，每张不超过 500 MB。上传时导出不透明且不含 Alpha 通道的图片，以确保兼容性。Apple 指定的尺寸如下：

素材	宽高比	最小尺寸	最大尺寸
EVENT_CARD	16:9	1920 × 1080	3840 × 2160
EVENT_DETAILS_PAGE	9:16	1080 × 1920	2160 × 3840

尽可能避免在图片中嵌入文字或徽标。考虑裁剪、渐变和 App Store 控件的影响； 如有预览，请检查 App Store Connect 中的预览，而不要假设图片中有固定百分比的区域是安全的。检查 每个目标本地化内容对应的媒体；不要假设主要语言区域中的素材会自动补齐其他语言区域中缺失的素材。请参阅 Apple 的媒体规范 和展示指南。

验证并提交

回读日程、深层链接、本地化文本和已交付媒体。使用视频片段时，也要检查视频。报告任何未经验证的预览或链接行为。

asc app-events view --event-id "EVENT_ID" --output json
asc app-events screenshots list --event-id "EVENT_ID" --locale en-US --paginate --output json

对于已有获批 iOS 版本的应用，在获得授权提交且无需继续处理现有提交时：

asc app-events submit --event-id "EVENT_ID" --app "APP_ID" --platform IOS --confirm --output json
asc review submissions-get --id "SUBMISSION_ID" --output json

第二条命令使用回执中的 submissionId。报告 Apple 返回的状态；提交成功的回执并不代表已获批准或已发布。如果应用没有获批的 iOS 版本，Apple 要求将此活动纳入首个版本的提交中。使用 asc-release-flow 准备该版本，然后按下方所示，使用 review items-add 将活动添加到预定的草稿中；跳过独立的 app-events submit 命令。需要新功能时，协调构建和活动发布。请参阅 Apple 的提交指南。

避免重复操作，妥善恢复

app-events submit 会创建新的审核提交、添加活动，然后提交。创建后发生故障时，可能会留下草稿，即使错误中没有显示提交 ID。重试前，请检查提交及其项目：

asc review submissions-list --app "APP_ID" --platform IOS --paginate --output json
asc review submissions-get --id "SUBMISSION_ID" --output json
asc review items-list --submission "SUBMISSION_ID" --paginate --output json

对于预定的 READY_FOR_REVIEW 草稿，请确认应用、平台和所有项目都属于获授权的提交。先修复活动。例如，Apple 报告缺少深层链接时，使用 asc app-events update --event-id "EVENT_ID" --deep-link "myapp://event/summer"。然后重复使用该草稿：

asc review items-add --submission "SUBMISSION_ID" --item-type appEvents --item-id "EVENT_ID" --if-exists skip
asc review submissions-submit --id "SUBMISSION_ID" --confirm

不要取消空的 READY_FOR_REVIEW 草稿：没有正在进行的审核可供取消。不要重新提交已在等待审核的提交。对于其他提交状态，请转交给 asc-submission-health 处理，并保留目标和获授权的工作。

403 FORBIDDEN_ERROR 可能表示存在实际访问限制。在判断为暂时性服务错误之前，请检查所选配置文件、应用访问权限和角色；一次 403 并不意味着应该轮换凭据或假定凭据有效。如果近期的成功调用支持暂时性故障的判断，请通过有限次数的退避重试读取操作，若错误持续则停止。对于结果不确定的创建或上传操作，重复执行前，请先列出已有资源并检查其交付状态，以避免重复。

如需了解当前服务提供商要求，请参阅 Apple 的活动设置指南。