配置 iOS 沙盒测试

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

在 iOS 设备上测试内购功能需要在 App Store Connect 和测试设备上进行正确的配置。这份指南涵盖了您需要了解的所有内容，以便开始使用沙盒测试。

前提条件

苹果开发者计划: 每年续费的活跃会员
协议: 已签署的“付费应用程序协议”，并已完成银行和税务信息
Xcode 项目: 配置了合适的包名和功能

设置流程

签署付费应用程序协议

在 App Store Connect 中，导航到 协议、税务和银行 并完成：
- 签署付费应用程序协议
- 添加您的银行信息
- 完成税务表
等待苹果批准您的信息（此过程可能需要24-48小时）。
创建沙盒测试用户

在 App Store Connect 中，前往 用户和访问 > 沙盒测试者.

点击 + 按钮创建一个新的沙盒测试者。

重要提示：使用尚未与 Apple ID 关联的电子邮件地址。您可以使用电子邮件别名：
- Gmail： youremail+test@gmail.com
- iCloud： youremail+test@icloud.com
配置测试设备 (iOS 12+)

从 iOS 12 开始，您不再需要注销 iTunes 帐户以测试购买。

在您的 iOS 设备上：
1. 打开设置
2. 点击 应用商店
3. 滚动到底部
4. 点击 沙盒帐户
5. 使用您的沙盒测试帐户登录
这比以前退出 iTunes 帐户的方法要方便得多!
配置 Xcode 项目

确保您的 Xcode 项目具有:

包标识符
- 必须与您的开发者中心中的标识符匹配
- 必须与 App Store Connect 中的标识符匹配
内购功能
1. 在 Xcode 中选择您的项目
2. 转到 签名 & 能力
3. 点击 功能性能力
4. 添加 应用内购买
创建应用内购买产品

在 App Store Connect 中，导航到您的应用并创建您的应用内购买产品（订阅、消耗性产品等）。

产品必须至少处于“准备就绪”状态才能进行沙盒测试。
测试您的实现

在测试设备上构建并运行您的应用。当您尝试购买时，您应该看到：

[环境：沙盒]

此确认表明您处于沙盒环境中，不会被收取实时货币。

重要注意事项

沙盒环境特征

无实际费用所有购买在沙盒模式下都是免费的
加速订阅订阅周期缩短以加快测试
- 1周订阅=3分钟
- 1个月订阅=5分钟
- 2个月订阅=10分钟
- 3个月订阅=15分钟
- 6个月订阅=30分钟
- 1 年订阅 = 1 小时
自动续订限制:sandbox 环境下订阅自动续订至 6 次
立即取消:已取消的订阅立即失效

沙盒账户管理

仅在测试设备上使用测试账户
不要使用个人 Apple ID 进行沙盒测试
测试账户可以无论地域购买任何产品
使用沙盒测试

使用沙盒测试

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

const { isBillingSupported } = await NativePurchases.isBillingSupported();
if (!isBillingSupported) {
  throw new Error('StoreKit not supported on this device');
}

// Fetch products (automatically uses sandbox when available)
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Make test purchase
const transaction = await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_monthly',
  productType: PURCHASE_TYPE.SUBS,
});

console.log('Test purchase successful!', transaction.transactionId);

验证

当配置正确时，您应该观察到：

沙盒标签 在购买时：“[环境：沙盒]”
产品加载 成功
购买完成 无实际费用
收据验证 正确
订阅将自动续期 自动续期（加速率）

故障排除

产品未加载：

确认 App Store Connect 的 bundle 标识符是否匹配
确认协议已签署并批准
确认产品至少达到“准备提交”状态
创建产品后等待 2-3 小时

“无法连接到 iTunes Store”：

确认沙盒账户配置正确
检查设备是否连接到互联网
尝试注销并重新登录沙盒账户
重启应用

购买失败：

检查Xcode控制台中的错误消息
验证In-App购买功能是否已启用
确保沙盒账户邮箱不是真实Apple ID
尝试创建新的沙盒测试账户

收据验证错误：

在测试中使用沙盒收据验证端点
生产端点： https://buy.itunes.apple.com/verifyReceipt
沙盒端点： https://sandbox.itunes.apple.com/verifyReceipt
原生购买插件会自动处理

订阅时长错误：

请记住，sandbox 中的订阅会加速
请使用上面的转换表格来预计时长
sandbox 中的订阅最多自动续费 6 次

“This Apple ID has not yet been used in the iTunes Store”:

这是新 sandbox 帐户的正常情况
继续购买以激活帐户
只会在首次使用时发生

最佳实践

创建多个测试帐户 针对不同测试场景
测试所有订阅时长 验证行为
测试取消和续订流程 验证收据验证
确保功能正常工作 测试恢复购买
验证功能 检查订阅升级/降级行为
验证行为 测试网络条件差的情况
__CAPGO_KEEP_0__

生产环境 vs. 测试环境

功能	测试环境	生产环境
实时收费	否	是
订阅时长	加速	正常
自动续订限制	6 次	无限
取消效果	立即	期限结束
收据端点	沙盒 URL	生产 URL
仅测试帐户	是	否