跳转到正文
Capgo - 构建、发布并更新 Capacitor 应用 Capgo

配置 iOS 沙盒测试

GitHub

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

前提条件

“前提条件”章节
  • Apple Developer Program：有效会员资格，按年续费
  • 协议：已签署“付费应用程序协议”并完成银行和税务信息填写
  • Xcode 项目：已配置正确的 bundle identifier 和 capabilities

设置流程

标题为“设置流程”的章节

  1. 签署付费应用程序协议

    在 App Store Connect 中，前往 协议、税务和银行业务 并完成以下操作：

    • 签署付费 App 协议
    • 添加银行信息
    • 填写税务表格

    等待 Apple 审核你的信息（可能需要 24-48 小时）。

  2. 创建 Sandbox 测试用户

    在 App Store Connect 中，前往 用户和访问 > Sandbox 测试员.

    点击 + 按钮，创建一个新的 Sandbox 测试员。

    重要提示: 请使用一个尚未关联 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. 使用您的沙盒测试账号登录

  4. 配置 Xcode 项目

    请确保您的 Xcode 项目已配置：

    Bundle 标识符

    • 必须与 Developer Center 中的标识符一致
    • 必须与 App Store Connect 中的标识符一致

    应用内购买权限

    1. 在 Xcode 中选择您的项目
    2. 前往 签名与功能
    3. 点击 + 功能
    4. 添加 App 内购买项目

  5. 创建 App 内购买项目

    在 App Store Connect 中，进入您的 App 并创建 App 内购买项目（订阅、消耗型项目等）。

    商品状态必须至少为“准备提交”，才能进行沙盒测试。

  6. 测试您的实现

    在测试设备上 build 并运行您的 App。当您尝试购买时，应该会看到：

    [环境：Sandbox]

    此确认信息表明你当前处于 Sandbox 环境，不会产生真实扣费。

重要注意事项

标题为“重要注意事项”的部分

Sandbox 环境特性

章节标题为“Sandbox 环境特性”
  • 无真实扣费: Sandbox 模式下所有购买均免费
  • 订阅周期加速: 订阅时长会缩短，以便更快测试
    • 1 周订阅 = 3 分钟
    • 1 个月订阅 = 5 分钟
    • 2 个月订阅 = 10 分钟
    • 3 个月订阅 = 15 分钟
    • 6 个月订阅 = 30 分钟
    • 1 年订阅 = 1 小时
  • 自动续订限制: 沙盒环境下的订阅最多自动续订 6 次
  • 立即取消: 已取消的订阅会立即过期

沙盒账号管理

标题为“沙盒账号管理”的章节
  • 为不同场景创建多个测试账号
  • 请仅在测试设备上使用测试账号
  • 请勿使用个人 Apple ID 进行 Sandbox 测试
  • 测试账号可购买任意商品，不受地区限制

使用 Sandbox 测试

标题为“使用 Sandbox 测试”的章节
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. Sandbox 横幅 在购买时显示：“[Environment: Sandbox]”
  2. 商品加载 成功
  3. 购买完成 且不会实际扣费
  4. 收据验证 通过
  5. 订阅将 自动续订（按加速频率）

故障排除

“故障排除”章节

商品无法加载：

  • 确认 Bundle ID 与 App Store Connect 一致
  • 检查协议是否已签署并获批
  • 确保商品状态至少为“可供提交”
  • 创建产品后请等待 2-3 小时

“无法连接到 iTunes Store”：

  • 确认 Sandbox 账号配置正确
  • 检查设备是否已联网
  • 尝试退出并重新登录 Sandbox 账号
  • 重启 App

购买失败且无任何提示：

  • 检查 Xcode 控制台中的错误信息
  • 确认已启用 In-App Purchase 能力
  • 确保 Sandbox 账号邮箱不是真实的 Apple ID
  • 尝试创建一个新的 Sandbox 测试账号

收据验证错误：

  • 测试时使用 Sandbox 收据验证端点
  • 生产环境端点： https://buy.itunes.apple.com/verifyReceipt
  • Sandbox 端点： https://sandbox.itunes.apple.com/verifyReceipt
  • native-purchases 插件会自动处理此操作

订阅时长错误：

  • 请记住，Sandbox 环境下的订阅周期会加速
  • 请参考上方的转换表查看预期时长
  • Sandbox 环境下订阅最多自动续订 6 次

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

  • 这对于新的 Sandbox 账号来说是正常现象
  • 继续完成购买以激活账号
  • 仅在首次使用时出现

最佳实践

标题为“最佳实践”的章节
  1. 创建多个测试账号 以覆盖不同的测试场景
  2. 测试所有订阅周期 以验证业务逻辑
  3. 测试取消订阅与续订 的完整流程
  4. 验证收据校验 是否工作正常
  5. 测试恢复购买 的功能
  6. 检查订阅升级/降级 行为
  7. 在弱网环境下进行测试

生产环境 vs. 沙盒环境

“生产环境 vs. Sandbox”章节
功能Sandbox生产环境
真实扣费否是
订阅时长加速常规
自动续订限制6 倍无限量
取消生效即时周期结束
收据端点沙盒 URL生产环境 URL
仅限测试账号是否

更多资源

标题为“更多资源”的章节

欲了解更多详情，请参阅 Apple StoreKit 官方文档 关于沙盒测试。

从配置 iOS 沙盒测试继续

标题为“从配置 iOS 沙盒测试继续”的部分

如果你正在使用 配置 iOS 沙盒测试 要规划商店审核与分发，请将其与 使用 @capgo/native-purchases 关于“使用 @capgo/native-purchases”中的原生能力， @capgo/capacitor-in-app-review 有关 @capgo/capacitor-in-app-review 中的实现细节， 使用 @capgo/capacitor-in-app-review 有关《使用 @capgo/capacitor-in-app-review》中的原生能力， @capgo/capacitor-native-market 有关 @capgo/capacitor-native-market 的实现细节，以及 使用 @capgo/capacitor-native-market 有关使用 @capgo/capacitor-native-market. 时的原生能力