配置 iOS 沙箱测试

在 iOS 上测试应用内购买需要在 App Store Connect 和测试设备上进行正确配置。本指南涵盖了开始沙箱测试所需的一切。

先决条件

• Apple 开发者计划：每年续订的活跃会员资格
• 协议：签署“付费应用协议”并填写银行和税务信息
• Xcode 项目：配置了正确的包标识符和功能

Note

银行和税务设置审批可能需要数小时到数天的时间。在测试之前充分完成此操作。

设置过程

1. 签署付费应用协议

   在 App Store Connect 中，导航至协议、税务和银行业务并完成：

   • 签署付费应用协议
   • 添加您的银行信息
   • 完整的税表

   等待 Apple 批准您的信息（这可能需要 24-48 小时）。

2. 创建沙盒测试用户

   在 App Store Connect 中，转到 用户和访问 > 沙盒测试人员。

   单击 ++ 按钮创建新的沙箱测试器。

   重要：使用尚未与 Apple ID 关联的电子邮件地址。您可以使用电子邮件别名：

   • Gmail：youremail+test@gmail.com
   • iCloud：youremail+test@icloud.com

   

3. 配置测试设备(iOS 12+)

   从 iOS 12 开始，您不再需要退出 iTunes 帐户来测试购买。

   在您的 iOS 设备上：

   1. 打开设置
   2. 点击 App Store
   3. 滚动到底部
   4. 点击沙盒帐户
   5. 使用您的沙盒测试帐户登录

   :::提示 这比注销 iTunes 帐户的旧方法方便得多！ :::

4. 配置Xcode项目

   确保您的 Xcode 项目具有：

   捆绑包标识符

   • 必须与您的开发者中心中的标识符匹配
   • 必须与 App Store Connect 中的标识符匹配

   应用内购买功能

   1. 在 Xcode 中选择您的项目
   2. 转到签名和功能
   3. 单击**+ 功能**
   4. 添加 应用内购买

5. 创建应用内购买产品

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

   产品必须至少处于“准备提交”状态才能进行沙盒测试。

6. 测试您的实施

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

   [环境：沙盒]

   此确认表明您处于沙盒环境中，并且不会向您收取真钱。

重要提示

沙箱环境特征- 无实际费用：沙盒模式下所有购买都是免费的

• 加速订阅：缩短订阅持续时间以加快测试速度
  • 1 周订阅 = 3 分钟
  • 1 个月订阅 = 5 分钟
  • 2 个月订阅 = 10 分钟
  • 3 个月订阅 = 15 分钟
  • 6 个月订阅 = 30 分钟
  • 1 年订阅 = 1 小时
• 自动续订限制：订阅在沙盒中最多自动续订 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);

验证

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

1. 购买时的沙盒横幅：“[环境：沙盒]”
2. 产品加载成功
3. 购买完成 无实际费用
4. 收据正确验证
5. 订阅自动续订（加速）

故障排除

未加载产品：

• 验证包标识符是否匹配 App Store Connect
• 检查协议是否已签署并获得批准
• 确保产品至少处于“准备提交”状态
• 创建产品后等待 2-3 小时

“无法连接到 iTunes Store”：

• 验证沙箱帐户配置正确
• 检查设备是否已连接到互联网
• 尝试退出并重新登录沙盒帐户
• 重新启动应用程序

购买悄然失败：

• 检查 Xcode 控制台是否有错误消息
• 验证应用内购买功能已启用
• 确保沙盒帐户电子邮件不是真实的 Apple ID
• 尝试创建一个新的沙箱测试帐户

收据验证错误：

• 在测试中使用沙箱收据验证端点
• 生产端点：https://buy.itunes.apple.com/verifyReceipt
• 沙箱端点：https://sandbox.itunes.apple.com/verifyReceipt
• 本机购买插件会自动处理此问题

错误的订阅期限：

• 请记住，沙箱中的订阅会加速
• 使用上面的换算表来了解预期的持续时间
• 沙盒中的订阅最多自动续订 6 次

“此 Apple ID 尚未在 iTunes Store 中使用”：

• 这对于新沙箱帐户来说是正常的
• 继续购买以激活帐户
• 仅在第一次使用时发生

最佳实践

1. 创建多个测试账户针对不同的测试场景
2. 测试所有订阅持续时间以验证行为
3. 测试取消和续订流程
4. 验证收据验证是否正常工作
5. 测试恢复购买功能
6. 检查订阅升级/降级行为
7. 网络条件较差的情况下测试

生产环境与沙盒环境

特色	沙盒	生产
实际收费	没有	是的
订阅时长	加速	正常
自动续订限制	6 次	无限
取消效果	立即	期末
收据端点	沙盒网址	制作网址
仅测试帐户	是的	没有

其他资源有关更多详细信息，请参阅关于沙盒测试的 官方 Apple StoreKit 文档。