在 Unity 项目中实现…

当需要在 Unity 中接入或迁移应用内购买（IAP），包括从原生 Android/iOS 计费或第三方包迁移时使用。

适用场景

解决思路

1. 先阅读 references/pre-check.md，扫描项目中的第三方 IAP 包、原生 Google Billing 和现有 Unity IAP 版本，确定路由路径；在路由确定前不要读取其他参考文件或做任何修改。
2. 按需读取参考文件：API 签名与代码示例见 references/api-notes.md；平台扩展（Apple、Google）见 references/platform-notes.md；编辑 IAPProductCatalog.json 见 references/codeless-catalog.md；v4→v5 迁移见 references/migration-v4-to-v5.md；原生 Google BillingClient 转换见 references/path-convert-native-google-billing.md；原生 iOS StoreKit 转换见 references/path-convert-native-storekit.md；Essential Kit 转换见 references/convert-essentialkit.md；UniPay 见 references/convert-unipay.md；RevenueCat 见 references/convert-revenuecat.md；Adapty 见 references/convert-adapty.md；无现有 IAP 的新项目接入见 references/path-add-iap-to-new-project.md；IAP D2C（Stripe/Coda，需 v5.4+）见 references/path-implement-iap-d2c.md。
3. 初始化流程：通过 UnityIAPServices.StoreController() 获取 StoreController（或通过 DefaultStore()、DefaultProduct()、DefaultPurchase() 获取各服务）；在调用 Connect() 之前订阅所有必需事件；await store.Connect() 连接平台商店；在 OnStoreConnected 中调用 store.FetchProducts(List<ProductDefinition>) 加载目录；在 OnProductsFetched 后商品即可展示和购买。
4. 在 Awake() 中执行初始化，确保 IAP 在其他 Start() 方法之前就绪。
5. 商品类型使用 ProductType.Consumable、ProductType.NonConsumable、ProductType.Subscription。
6. 获取商品：将商品定义为 List<ProductDefinition> 并传给 store.FetchProducts()；当 Apple/Google 商品 ID 不同时使用 StoreSpecificIds；复杂目录使用 CatalogProvider 管理商品集和商店特定 ID。
7. 区分 GetProducts()（返回缓存列表，同步，若未调用 FetchProducts 则为旧数据）、FetchProducts()（向商店查询最新价格/可用性并更新缓存）、GetProductById(id)（按 ID 返回单个缓存商品）；依赖 GetProducts() 前必须先调用 FetchProducts()。
8. 两步购买流程：调用 store.PurchaseProduct(product) 发起平台购买对话框；OnPurchasePending 触发并收到 PendingOrder；校验收据并向玩家发放内容；调用 store.ConfirmPurchase(pendingOrder) 完成交易；OnPurchaseConfirmed 触发并收到 Order 基类型，用模式匹配区分 ConfirmedOrder（成功）与 FailedOrder（确认失败）。
9. 发放内容后必须调用 ConfirmPurchase(pendingOrder)；未确认的购买会在下次启动时重新投递以防丢失。
10. 去重：OnPurchasePending 可能对同一购买多次触发（例如确认前应用重启），始终检查内容是否已发放。
11. 消耗型商品：已确认的消耗型购买不会由 FetchPurchases 返回，需自行跟踪消耗型发放（例如存入 Cloud Save 或 Economy）。
12. 延迟购买：OnPurchaseDeferred 在 iOS Ask-to-Buy 和 Google Play 延迟购买时触发，不要发放内容，等批准后的 OnPurchasePending。
13. 恢复交易：调用 store.RestoreTransactions(callback) 重新投递非消耗型和订阅购买，每次恢复都会触发 OnPurchasePending；iOS 为符合 Apple App Store 要求必须提供“Restore Purchases”按钮；Apple 非续订订阅无法通过 RestoreTransactions 恢复，需在服务端跟踪。
14. 收据校验：Google Play 使用 CrossPlatformValidator 配合 GooglePlayTangle.Data() 进行本地校验；Apple（StoreKit 2）本地校验为空操作，使用 order.Info.Apple?.jwsRepresentation 做服务端校验；通过 Unity 编辑器的 Services > In-App Purchasing > Receipt Validation Obfuscator 生成 tangle 数据。
15. 权益检查：当没有 Order 但想知道某商品状态时（替代 v4 的 product.hasReceipt），调用 store.CheckEntitlement(product) 并处理 store.OnCheckEntitlement，检查 entitlement.Status == EntitlementStatus.FullyEntitled；若已有 Order 则检查其类型：PendingOrder 对应 EntitledUntilConsumed（消耗型）或 EntitledButNotFinished（非消耗型/订阅），ConfirmedOrder 对应 FullyEntitled；EntitlementStatus 取值有 FullyEntitled、EntitledUntilConsumed、EntitledButNotFinished、NotEntitled、Unknown。
16. 获取已有购买：store.FetchPurchases() 从商店获取所有当前购买，适合应用启动时使用；GetPurchases() 返回缓存列表，FetchPurchases() 查询商店并覆盖缓存列表；FetchPurchases() 每次调用都会替换整个缓存列表，且只重新获取非消耗型和订阅，已确认的消耗型不会返回。
17. 订阅信息位于 IPurchasedProductInfo，通过 order.Info.PurchasedProductInfo 访问，不在 CartItem 上（CartItem 只有 Product 和 Quantity）。
18. IsSubscribed() 返回 Result 枚举（True/False/Unsupported），不是 bool；使用 == Result.True 做空安全比较。
19. 始终同时订阅成功和失败事件，不订阅失败事件会产生运行时警告：FetchProducts() 对应 OnProductsFetched/OnProductsFetchFailed；FetchPurchases() 对应 OnPurchasesFetched/OnPurchasesFetchFailed；Connect() 对应 OnStoreConnected/OnStoreDisconnected；PurchaseProduct() 对应 OnPurchasePending/OnPurchaseFailed；CheckEntitlement() 对应 OnCheckEntitlement。
20. 始终订阅 OnPurchaseDeferred，它在 iOS Ask-to-Buy 和 Google Play 延迟购买时触发，不订阅会静默丢弃延迟购买。
21. 在调用 Connect() 之前订阅事件，因为上一会话的待处理购买可能立即触发。
22. 失败描述属性名不可互换，用错会导致 CS1061：StoreConnectionFailureDescription 用 .message/.Message（不是 .reason）；ProductFetchFailed 用 .FailureReason、.FailedFetchProducts（不是 .Message）；FailedOrder 用 .FailureReason、.Details；PurchasesFetchFailureDescription 用 .message、.failureReason、.Message、.FailureReason。
23. 验证：确认项目编译无错误；确认所有 API 调用匹配 api-notes.md 中的 v5 签名，不要使用 v4 遗留模式（IStoreListener、UnityPurchasing.Initialize、ConfigurationBuilder）；检查 api-notes.md 中的“Anti-Hallucination: Common v5 Mistakes”表，不要使用 OnStoreConnectionFailed（用 OnStoreDisconnected），不要向 FetchProducts/FetchPurchases 传回调（用事件），不要使用 product.receipt（用 order.Info.Receipt）；检查所有必需事件在 Connect() 之前订阅；验证两步购买流程 OnPurchasePending → 发放内容 → ConfirmPurchase(pendingOrder)；确认每个异步操作都订阅了成功和失败事件；处理订阅时确认 IsSubscribed() 用 == Result.True 比较而非转 bool；若更新文件与遗留版本共存于同一项目，使用唯一命名空间（如加 .Updated 后缀）避免 CS0101/CS0111 编译错误；若项目订阅了 OnAuthAccountChanged（v5.4+），确认处理器从头重新获取商品和购买——Unity IAP 在触发该事件前会清空两个缓存，不要在处理器内读取 GetProducts() 或 GetPurchases()。

适用边界 · 注意事项

• 在未先阅读 references/pre-check.md 并确定路由路径之前，不要读取其他参考文件或做任何修改。
• 不要使用 v4 遗留模式（IStoreListener、UnityPurchasing.Initialize、ConfigurationBuilder）、OnStoreConnectionFailed、向 FetchProducts/FetchPurchases 传回调或 product.receipt。
• 不要在 OnAuthAccountChanged 处理器内读取 GetProducts() 或 GetPurchases()，因为 Unity IAP 在触发该事件前会清空两个缓存。