Adapty iOS Sandbox 測試完整指南

本文基於 Adapty 官方文檔整理，詳細說明如何在 iOS 應用中進行 Sandbox 環境的內購測試，確保付款流程在上線前運作正常。

概述

在 iOS 應用開發中，內購（In-App Purchase）功能的測試至關重要。Apple 提供的 Sandbox 測試環境讓開發者能夠在不產生實際費用的情況下，完整測試購買流程。本文將詳細介紹如何使用 Adapty SDK 進行 Sandbox 測試。

測試前置需求

在開始測試前，請確認以下項目已完成：

1. Adapty Dashboard 設定：已完成 store 整合、產品設定、SDK 整合
2. App Store Connect 產品狀態：產品已標記為 Ready to submit
3. 測試裝置：建議使用真機測試（模擬器無法完整測試付款對話框和生物辨識）

測試方式選擇

根據測試人員角色，可選擇以下兩種方式：

方式	適用對象	優點
Xcode Build + 真機	開發者、QA 工程師	即時除錯、完整日誌
TestFlight + Sandbox 帳號	外部測試人員、產品經理	接近正式環境、無需開發工具

Step 1：建立 Sandbox 測試帳號

每次測試建議建立新帳號，舊帳號的購買紀錄會影響測試結果。

建立步驟

1. 前往 App Store Connect → Users and Access → Sandbox → Test Accounts
2. 點擊 + 新增帳號
3. 填寫帳號資料
   • Country or Region：會影響產品可用性和顯示幣別
4. 點擊 Create 完成建立

Email 建立技巧

• Gmail 子地址：可使用 + 號建立子地址（如 [email protected]），所有郵件會送到原信箱
• 虛擬 Email：可使用不存在的 email 地址，但登入時需拒絕雙重驗證提示

Step 2：啟用 Developer Mode（真機）

使用真機測試前，必須啟用開發者模式：

1. 使用傳輸線連接 iPhone 到 Mac
2. 開啟 Xcode（系統會自動偵測裝置）
3. 在 iPhone 上操作：
   • 前往 設定 → 隱私權與安全性 → 開發者模式
   • 開啟開關並重新啟動裝置

Step 3：從 TestFlight 下載 App

若使用 Xcode Build 方式測試，可跳過此步驟。

1. 確保 iPhone 已登入正式 Apple ID
2. 從 TestFlight 下載目標 app
3. 下載後不要立即開啟 app，直接進行 Step 4

這個順序很重要，因為需要先切換到 Sandbox 帳號再開啟 app，避免購買記錄綁定到錯誤的帳號。

Step 4：切換到 Sandbox 帳號

登出正式帳號

1. 前往 設定 → [你的 Apple ID]
2. 點擊 媒體與購買項目 → 登出

登入 Sandbox 帳號

1. 前往 設定 → 開發者（若未顯示，回到 Step 2）
2. 滑動到 Sandbox Apple Account 區塊
3. 點擊 Sign In，輸入 Sandbox 帳號密碼

Step 5：清除購買記錄

新建立的 Sandbox 帳號可跳過此步驟。重複測試時必須執行。

清除步驟

1. 前往 設定 → 開發者 → Sandbox Apple Account
2. 點擊 Manage
3. 進入 Account Settings
4. 點擊 Clear Purchase History

注意事項

重複測試時，需先登出再重新登入 Sandbox 帳號，以清除裝置端的快取資料。

Step 6：執行測試購買

Xcode Build 方式

1. 將真機連接到 Mac
2. 在 Xcode 中選擇目標裝置
3. 點擊 Run（⌘R）
4. App 安裝完成後開始測試購買流程

TestFlight 方式

直接開啟從 TestFlight 下載的 app，進行測試購買。

Sandbox 訂閱續訂時間表

Sandbox 環境中的訂閱週期會大幅縮短，方便快速測試續訂邏輯。Apple 提供 4 種續訂速度選項，可在 App Store Connect 的 Sandbox 帳號設定中調整。

預設續訂速度（Monthly Renewal Every 5 Minutes）

正式訂閱週期	Sandbox 續訂間隔	Billing Retry 時長	Grace Period 時長
1 週	3 分鐘	10 分鐘	3 分鐘
1 個月	5 分鐘	10 分鐘	5 分鐘
2 個月	10 分鐘	10 分鐘	5 分鐘
3 個月	15 分鐘	10 分鐘	5 分鐘
6 個月	30 分鐘	10 分鐘	5 分鐘
1 年	1 小時	10 分鐘	5 分鐘

其他可選續訂速度

選項	月訂閱續訂間隔	年訂閱續訂間隔	適用情境
Every 3 minutes	3 分鐘	36 分鐘	快速驗證續訂邏輯
Every 5 minutes（預設）	5 分鐘	1 小時	一般測試
Every 30 minutes	30 分鐘	6 小時	模擬較長週期行為
Every hour	1 小時	12 小時	測試 Grace Period

續訂限制

• 訂閱最多自動續訂 12 次，第 13 次續訂嘗試時會自動停止
• 這讓測試者能在有限時間內完整測試訂閱生命週期

常見問題排除

TestFlight 忘記切換 Sandbox 帳號

症狀：購買記錄綁定到正式 Apple ID，導致無法透過 Sandbox 設定清除。

解決方式：

1. 從裝置刪除 app
2. 重新執行 Step 3 至 Step 6

測試 Promotional Offer 失敗

原因：Offer 資格判斷依賴購買紀錄，舊紀錄會影響判斷結果。

解決方式：

• 執行 Step 5 清除所有購買記錄
• 或使用全新 Sandbox 帳號進行測試

購買時登入 Sandbox 帳號失敗

原因：購買對話框中的登入不會正確綁定 Sandbox 環境。

解決方式： 必須事先在設定中登入 Sandbox 帳號（Step 4），購買過程中的登入不會生效。

模擬器測試（替代方案）

若無法使用真機，可透過 StoreKit Configuration File 在模擬器上測試：

設定步驟

1. 在 Xcode 中建立設定檔：File → New → File → StoreKit Configuration File
2. 加入測試產品（Product ID 需與 Adapty Dashboard 一致）
3. 設定 Scheme：Edit Scheme → Run → Options → StoreKit Configuration
4. 選擇剛建立的設定檔
5. Build 到模擬器

模擬器測試限制

• 購買結果不會同步到 Adapty Dashboard
• 僅能測試本地購買流程
• 無法測試伺服器端驗證
• 不支援生物辨識驗證

測試檢查清單

完成測試前，建議逐項確認：

• Sandbox 帳號已建立且可正常登入
• 裝置已啟用 Developer Mode
• 已在設定中登入 Sandbox 帳號（非購買時登入）
• 購買記錄已清除（重複測試時）
• 購買流程正常完成
• 交易紀錄出現在 Adapty Dashboard
• 訂閱續訂邏輯正確執行

結論

Sandbox 測試是確保 iOS 內購功能正常運作的關鍵步驟。透過本文的流程，你可以：

1. 正確建立和管理測試帳號
2. 避免常見的帳號混淆問題
3. 有效測試各種購買情境
4. 確保上線前的付款流程穩定

建議在每次發布新版本前，都完整執行一次 Sandbox 測試流程，以確保內購功能的可靠性。

參考資料

Adapty 官方文檔

• Test in-app purchases in iOS Sandbox

Apple Developer 官方文檔

• Manage Sandbox Apple Account settings — 完整續訂時間表與 Billing Retry / Grace Period 設定
• Testing In-App Purchases with Sandbox
• App Store Connect: Sandbox Testing