0. 写在前面Apple 订阅的难点往往不在「调起支付」而在App Store Connect 商品、沙盒账号、Server Notifications客户端验单与服务端权益一致续费、换档、退款、试用等生命周期要持续同步SubHub 把StoreKit 2 购买 → 服务端验单 → 权益 → Webhook收成一条链路客户端用 iOS SDK商店差异由平台消化。资金仍走 App StoreSubHub不是支付网关也不抽应用流水。本文将按真实接入顺序写商店侧 → SubHub 控制台 → ASN → SDK → 沙盒验证 → 常见坑。1. 你将得到什么完成后你应能在 App Store Connect 建好自动续订订阅在 SubHub 配好 Apple API 密钥与商品映射配好 App Store Server Notifications V2ASN用 SubHub iOS SDK 完成configure→setUserId→purchase→hasEntitlement用沙盒账号买一笔在控制台看到购买与权益环境要求简述iOS 15StoreKit 2Xcode 16当前 iOS SDK 以 SPM 二进制分发版本以 iOS SDK 文档 为准撰写时常见为 1.0.xApp Store Connect 权限能建 IAP、能创建 API 密钥SubHub 账户可用免费版起步2. 整体架构用户点购买 → StoreKit 2 与 Apple 完成支付 → SubHub iOS SDK 把交易交给 SubHub 验单 → SubHub 调 App Store Server API / 订阅状态写入购买与权益 → 可选你的服务端收 Webhook更新自家业务库 → 客户端 hasEntitlement / entitlements 决定是否解锁 续费 / 退款 / 过期 … → Apple 推 ASN V2 到 SubHub → SubHub 更新权益并可选再推你的 Webhook要点商品 IDSKU必须与 App Store Connect 的 Product ID完全一致权益标识entitlement业务上的「有没有会员」同组多档可共用一个权益 ID换档只换 SKUSandbox / Production由验单时 Apple JWS 自动识别SDK 与控制台都不用选手动环境3. App Store Connect 侧准备3.1 创建自动续订订阅登录 App Store Connect进入对应 App →订阅/App 内购买项目创建订阅群组再创建自动续订订阅如周 / 月 / 年记下每个档位的产品 ID例如com.yourapp.premium.monthly建议同组多档月 / 年共用业务权益如premium在 SubHub 里也会这样配。3.2 沙盒测试账号用户与访问 →沙盒→ 测试账户新建 Sandbox Apple ID与日常 Apple ID 分开真机或模拟器登录该沙盒账号后再测购买3.3 创建 App Store Connect API 密钥.p8SubHub 验单与订阅状态依赖 Server API需要项在哪拿Issuer ID用户与访问 → 集成 → Issuer IDKey ID创建 API 密钥时显示Private Key (.p8)下载一次妥善保存权限建议能访问 App 内购买 / 相关 API按你账号角色选择合适访问权限。注意.p8 只显示/下载一次丢失需重新创建密钥。4. SubHub 控制台配置注册并登录https://subhub.com.cn4.1 创建应用控制台创建应用填写名称、Bundle ID须与 Xcode / ASC 一致、平台选 iOS记下应用 ID形如app_xxx后面 ASN URL、SDK 都要用说明应用创建后一般不可删除Bundle ID 创建后通常不可改。4.2 生成 API 密钥在API 密钥页生成Publishable Keypk_live_...→ 放客户端 SDKSecret Keysk_live_...→ 仅服务端 REST / 运维禁止打进 App 或提交 Git同一账户下多应用可共用一套密钥用X-App-Id/ SDK 的appId区分应用。4.3 填写 Apple 配置应用详情 →Apple 配置粘贴Issuer ID密钥 IDKey IDPrivate Key.p8 文件全文私钥在 SubHub 侧加密存储保存后一般不回显。环境以每次验单结果为准。4.4 配置商品映射 SKU → 权益在应用下创建商品例如SubHub 字段示例说明产品标识符com.yourapp.premium.monthly ASC Product ID类型订阅subscription自动续订选这个权益标识premium年档可填同一个premium要点标识符必须与商店逐字符一致无单独「权益菜单」——写在商品上即可验单成功后平台自动写成员权益刚建 SKU 立刻买可能productNotFound重启 App 或重新configure后再试5. 配置 App Store Server Notifications V2强烈建议必做未配 ASN 时往往只有首次客户端 verify 有效续费、退款、过期等不会自动进 SubHub。5.1 通知 URL每个 SubHub 应用一条独立地址把{app_id}换成你的app_xxxhttps://subhub.com.cn/api/v1/providers/apple/apps/{app_id}示例https://subhub.com.cn/api/v1/providers/apple/apps/app_abc1235.2 在 ASC 里填写App Store Connect → 你的 App →App 信息→App Store 服务器通知Server Notifications生产环境 URL填上面的地址沙盒 URL建议同样填或按 ASC 当前 UI 分别配置保存后可用沙盒续费/退款流程验证 SubHub 控制台是否出现对应事件也可在自有 Webhook 侧观察。6. 集成 SubHub iOS SDK6.1 安装Swift Package ManagerXcode → Package Dependencies添加https://github.com/MoYoDream/subhub-ios-sdk选与文档一致的版本如1.0.2以 Release 为准。6.2 初始化顺序务必记住推荐顺序注册onDeferredSyncFailure延迟同步失败回调configure(publishableKey:appId:)登录或首次安装后setUserId再purchase/hasEntitlement/entitlements/restore/syncTransactions未setUserId就买会报userIdRequired一类错误。setUserId传的是你业务侧的用户 IDexternal_user_id例如 Firebase UID。SubHub 用它关联成员与权益。6.3 最小代码importSubHubtrySubHubSDK.configure(publishableKey:pk_live_xxx,appId:app_xxx)tryawaitSubHubSDK.setUserId(firebase_uid_8a2b)lethasEntitlementtryawaitSubHubSDK.hasEntitlement(premium)6.4 SwiftUI 完整落点含回前台同步importSwiftUIimportSubHubmainstructMyApp:App{Environment(\.scenePhase)privatevarscenePhaseinit(){do{SubHubSDK.onDeferredSyncFailure{errorinprint(SubHub deferred sync:,error)}trySubHubSDK.configure(publishableKey:pk_live_xxx,appId:app_xxx)}catch{assertionFailure(SubHub configure failed:\(error))}}varbody:someScene{WindowGroup{ContentView()}.onChange(of:scenePhase){phaseinguardphase.activeelse{return}Task{try?awaitSubHubSDK.syncTransactions()}}}}structContentView:View{StateprivatevarisPremiumfalsevarbody:someView{VStack(spacing:16){Text(isPremium?已开通会员:免费用户)Button(购买月订阅){Task{awaitbuy()}}}.task{awaitbootstrap()}}funcbootstrap()async{do{tryawaitSubHubSDK.setUserId(user_123)isPremiumtryawaitSubHubSDK.hasEntitlement(premium)}catch{print(bootstrap:,error)}}funcbuy()async{do{// productId App Store Connect / SubHub 商品标识符_tryawaitSubHubSDK.purchase(productId:com.yourapp.premium.monthly,refreshEntitlements:true)isPremiumtryawaitSubHubSDK.hasEntitlement(premium)}catchSubHubError.userCancelled{// 用户取消}catchSubHubError.purchasePending{// Ask to Buy家长批准后依赖回前台 syncTransactions}catch{print(purchase:,error)}}}说明purchase默认不一定拉全量权益订阅场景建议refreshEntitlements: true或买后再调entitlements()同组升级 / 降级iOS 直接purchase(新 SKU)即可不必单独 upgrade APIrestore不是每次冷启动必调自购且服务端已有权益时setUserId→hasEntitlement即可家庭共享受益人首次、店外兑换促销码等才需要restore7. 可选你自己的服务端 Webhook若发货、开通权限以你服务器为准在 SubHub 控制台配置出站 Webhook监听如purchase.completed、权益变更、退款等事件。消耗型必须以 Webhook 驱动发货订阅 / 会员多数可用 SubHub 权益 客户端hasEntitlement复杂业务再叠加 Webhook。详见Webhook 文档8. 沙盒联调清单按顺序勾选ASC 订阅 Product ID 与 SubHub 商品标识符一致Apple Issuer / Key ID / .p8 已保存且无报错ASN V2 URL 含正确app_xxxSDKonDeferredSyncFailure→configure→setUserId→purchase使用Sandbox Apple ID且测试用独立external_user_id避免沙盒权益污染正式测试账号购买成功后hasEntitlement(premium) true控制台能看到对应购买Sandbox 交易会标store_environmentsandbox试用 / Introductory OfferASC 配好后沙盒购买写入记录Webhook enrichment 里关注isTrial/offerType不要只看 amount 0。9. 订阅换档与「productId 对不上」必读同组升级、降级「下周期再生效」时常出现某一笔 Transaction 的productId仍是旧档renewalInfo.productId才是当前应授予档autoRenewProductId是下周期档SubHub 在配置了 .p8、能打Subscription Status API时会以 Apple 订阅状态纠正入账商品客户端仍purchase(新 SKU)响应里的商品标识可能与你传入的 SKU 不一致以 Apple 为准。落地原则建议当前应发权益优先信订阅状态里的当前商品权益层用稳定的premium一类 ID不要把「有没有会员」绑死在某一个 SKU 字符串上更多排查思路见社区技术文与官方 订阅生命周期。10. 常见问题Q: 能买但 SubHub 一直验不过检查 .p8 / Issuer / Key IDBundle ID 是否一致商品是否已在 SubHub 创建。Q: 首次可以续费没反应几乎都是没配 ASN或 URL 里app_id错了。Q:productNotFound控制台商品 ID 与 ASC 不一致或新建后客户端缓存未刷新——重启 App / 重新 configure。Q: 要不要每次启动 restore一般不要。自购且服务端已有权益setUserIdhasEntitlement。例外家庭共享受益人首次、店外兑换等见何时调用哪个 API。Q: Ask to BuySDK 会走purchasePending批准后靠自动同步并在回前台再syncTransactions。Q: 非续期订阅季票ASC 的 Non-Renewing 在 SubHub 侧有单独约定expiresAt可能为空业务到期要自己算。自动续订请用本文的subscription路径。见文档 Apple 非续期订阅。11. 小结对接 Apple 订阅到 SubHub可以记成五步ASC 建订阅 沙盒账号 .p8SubHub 建应用、密钥、Apple 配置、商品SKU 权益映射配 ASN V2 到.../providers/apple/apps/{app_id}iOS SDKconfigure→setUserId→purchase/hasEntitlement沙盒买一笔核对控制台与权益官方入口官网https://subhub.com.cn文档https://subhub.com.cn/docsApple 专题https://subhub.com.cn/docs/apple快速开始https://subhub.com.cn/docs/quick-start有具体报错码如verificationFailed/quota_exceeded可以把控制台与 Xcode 日志打码后对照 错误码文档 排查。本文步骤以 SubHub 公开文档为准商店后台文案可能随 Apple 改版略有差异请以 App Store Connect 当前界面为准。