Local Testing with a .storekit File

Develop and QA the purchase and restore flows offline with a bundled StoreKit configuration file, without a backend or a real account.

Local testing runs OnsideKit fully offline against a bundled .storekit configuration file. Products come from the file, login is automatic and fake, and purchases and restores run against a local simulation — no backend, no registered app, and no real Onside account.

Enable it

1. Add a StoreKit configuration file to your app target — for example LocalProducts.storekit. (Xcode can create one via File → New → File → StoreKit Configuration File.)

2. Pass its base name (no extension) to initialize:

Onside.initialize(storeKitConfigurationName: "LocalProducts")

When storeKitConfigurationName is nil (the default), the SDK runs normally against the live backend. The choice is fixed at the first initialize call.

On success the SDK logs:

[Onside]: ✅ Initialized for local testing with N product(s) from LocalProducts.storekit

How it behaves

• Products come from the .storekit file. makeProductsRequest returns the configured products, matched by identifier.

• Login is automatic and offline — the SDK commits a synthetic session with no phone verification or store-app handoff. requestLogin "succeeds" instantly, and the storefront country is the one you set in the file (see _storefront below). logout() still clears it.

• Purchases present a fake Apple-Pay-style sheet (no real charge) and complete the transaction through the normal payment queue. Restorable products (non-consumables and subscriptions) are remembered locally; re-buying one shows an "already purchased" alert.

• Restore replays the locally remembered purchases.

The standard OnsideKit APIs are unchanged — the same queue, observers, and transaction flow. This is the recommended way to exercise the purchase UI, including the storefront/price-change gate, without a backend.

Not supported in local testing

Two APIs require a real account and return a dedicated error:

• Onside.presentPaymentMethodsManager(completion:) → .notSupportedInLocalTesting

• Onside.makeSignedInAppsHistoryRequest() → .notSupportedInLocalTesting

Reset between runs

Onside.resetLocalTestingState()

This clears the locally remembered purchase history so you can simulate a fresh install — restorable products are forgotten and re-buying one shows the full payment sheet again. It does not clear the fake login or the parsed products.

The .storekit file

OnsideKit reads a subset of Apple's StoreKit configuration format.

{
  "products": [
    {
      "productID": "remove_ads",
      "referenceName": "Remove Ads",
      "type": "NonConsumable",
      "displayPrice": "4.99",
      "localizations": [
        { "locale": "en_US", "displayName": "Remove Ads", "description": "Removes all ads." }
      ]
    }
  ],
  "subscriptionGroups": [
    {
      "id": "21F5C0E3",
      "name": "Premium",
      "localizations": [
        { "locale": "en_US", "displayName": "Premium", "description": "" }
      ],
      "subscriptions": [
        {
          "productID": "subscription_monthly",
          "referenceName": "Premium Monthly",
          "type": "RecurringSubscription",
          "displayPrice": "9.99",
          "recurringSubscriptionPeriod": "P1M",
          "localizations": [
            { "locale": "en_US", "displayName": "Premium Monthly", "description": "Monthly premium." }
          ]
        }
      ]
    }
  ],
  "settings": {
    "_locale": "en_US",
    "_storefront": "US"
  }
}

Supported fields

• products[]: productID, referenceName, type (Consumable → consumable; anything else → non-consumable), displayPrice, localizations[].

• subscriptionGroups[]: id, name, localizations[], subscriptions[].

• subscriptions[]: productID, referenceName, type, displayPrice, recurringSubscriptionPeriod (ISO-8601 duration, e.g. P1M), localizations[].

• localizations[]: locale, displayName, description.

• settings: _locale (preferred localization, default en_US) and _storefront (the testing storefront/country code — set this explicitly).

In local testing, all prices render in EUR — only the numeric value comes from displayPrice. Set _storefront to the ISO country code you want to test; the storefront country drives region-dependent behavior.