diff --git a/docs/getting-started/configuring-sdk.mdx b/docs/getting-started/configuring-sdk.mdx index 48fd029e9..6c29ff433 100644 --- a/docs/getting-started/configuring-sdk.mdx +++ b/docs/getting-started/configuring-sdk.mdx @@ -6,6 +6,12 @@ hidden: false If this is your first time integrating RevenueCat into your app, we recommend following our [Quickstart](/getting-started/quickstart) guide. +:::success Test Store works out of the box +Once configured, the SDK automatically works with your Test Store products—no additional setup required. You can start testing purchases immediately without connecting to the App Store or Google Play. + +**SDK Version Requirements:** Test Store requires minimum SDK versions (iOS 5.43.0, Android 9.9.0, Flutter 9.8.0, React Native 9.5.4, Capacitor 11.2.6, Cordova 7.2.0, Unity 8.3.0, KMP 2.2.2, Web 1.15.0). [See all versions](/test-and-launch/sandbox#testing-with-revenuecat-test-store). +::: + :::info Using an older SDK (v3.x) View our migration guide to v4.x [here](/sdk-guides/ios-native-3x-to-4x-migration). ::: @@ -73,6 +79,30 @@ As detailed in the sample code above, debug logs can be enabled or disabled by s Debug logs will provide detailed log output in Xcode or LogCat for what is going on behind the scenes and should be the first thing you check if your app is behaving unexpectedly, and also to confirm there aren't any unhandled warnings or errors. +## Testing with Test Store + +After configuring the SDK, you can immediately start testing with your Test Store products—no additional SDK configuration required. Simply use your Test Store API key when initializing the SDK, and test purchases will work automatically. + +See [Sandbox Testing](/test-and-launch/sandbox) for details on testing with Test Store vs platform sandboxes. + +### Switching between Test Store and Real Stores + +Test Store uses a **separate API key** from your real store API keys. This allows you to control which store your app communicates with: + +- **Test Store API Key**: Use during development and testing +- **Platform Store API Keys** (iOS, Android, etc.): Use for production builds + +You can find both types of keys in **Project Settings > API keys** in the RevenueCat dashboard. Switch between them by changing which key you pass to the SDK configuration. + +:::danger CRITICAL: Never submit apps with Test Store API key +**You must NEVER submit an app to the App Store or Google Play that is configured with a Test Store API key.** Always use the correct platform-specific API key (iOS, Android, etc.) for release builds. + +We recommend using build configurations or environment variables to automatically use the correct API key for each build type: + +- **Development/Debug builds**: Test Store API key +- **Production/Release builds**: Platform-specific API key (iOS, Android, etc.) + ::: + ## Additional Configuration The SDK allows additional configuration on first setup: @@ -155,6 +185,9 @@ Called whenever _Purchases_ receives an updated `CustomerInfo` object. This may ## Next steps -Once you've configured the SDK, it's time to add your products in the dashboard. +Once you've configured the SDK, you're ready to set up your products: + +- **Start with Test Store** (recommended): Your project already has a Test Store provisioned. [Create test products](/offerings/products-overview) and start testing immediately. +- **Connect real stores**: When you're ready for production, [configure your products](/offerings/products-overview) in App Store Connect, Google Play Console, or other platforms. - + diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index ae4b7733b..5055ebb5b 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -15,49 +15,17 @@ Before continuing with this guide, follow our [Setting up RevenueCat](/welcome/o ## 2. Product Configuration -### Store Setup +Before using the SDK, you need to configure your products, entitlements, and offerings in the RevenueCat dashboard. Every new project comes with a **Test Store** automatically configured, so you can start immediately without connecting to Apple or Google. -Before you can start using RevenueCat to fetch products, you must configure your products in the respective stores. See the following guides for [App Store Connect](/getting-started/entitlements/ios-products), [Google Play Console](/getting-started/entitlements/android-products), [Amazon Appstore](/getting-started/entitlements/amazon-product-setup), [Stripe](/getting-started/entitlements/stripe-products), and [Paddle](/getting-started/entitlements/paddle-products) for help navigating through this process. + -If you are selling iOS products, be sure to sign your 'Paid Applications Agreement' and fill out your bank and tax information in **App Store Connect > Agreements, Tax, and Banking**. **This needs to be completed before you can test any purchases**. - -:::info Want to skip the store setup while testing? -On iOS, you can delay configuring products in App Store Connect by testing with StoreKit Configuration files instead. These config files require minimal setup and are configurable via Xcode directly. - -Read more about setting up StoreKit Configuration files in our [Sandbox Testing](/test-and-launch/sandbox/apple-app-store#ios-14-only-testing-on-the-simulator) guide. +:::info Already configured your products? +Continue to SDK installation below. ::: -### Configure Products and Entitlements in RevenueCat - - - -Once your in-app products have been configured in [App Store Connect](/getting-started/entitlements/ios-products), [Google Play Console](/getting-started/entitlements/android-products), [Amazon Appstore](/getting-started/entitlements/amazon-product-setup), [Stripe](/getting-started/entitlements/stripe-products), or [Paddle](/getting-started/entitlements/paddle-products) you'll need to copy that configuration into the RevenueCat dashboard. RevenueCat uses an Entitlements system to control access to premium features, and Offerings to manage the set of products you offer to customers. - -Entitlements are the level of access that a customer is "entitled" to after purchasing a specific product, and Offerings is a simple way for you to organize the in-app products you wish to "offer" on your paywall and configure them remotely. We **recommend** utilizing these features to simplify your code and enable you to change products without releasing an app update. - -See [Configuring Products](/getting-started/entitlements) to set up your products and then organize them into Offerings or Entitlements. - -![Offerings Diagram](/docs_images/offerings/offerings-visual.png) - -### Build and Design Your Paywall - - - -After configuring your offerings, you can jump right into designing a paywall (even before installing the SDK!) by choosing Paywalls in the sidebar of your project dashboard. - -RevenueCat provides several pre-built, customizable paywall templates that you can use to rapidly create a paywall. - -If you'd prefer to install the SDK before designing your paywall, you can always come back to this step later. - -{} - -
-
- -_Want to build your own custom paywall? See [Displaying Products](/getting-started/displaying-products), [Making Purchases](/getting-started/making-purchases), and [Restoring Purchases](/getting-started/restoring-purchases) for more information on manual implementation._ +:::tip SDK Version Requirements +Test Store requires minimum SDK versions (iOS 5.43.0+, Android 9.9.0+, etc.). See [Sandbox Testing](/test-and-launch/sandbox#testing-with-revenuecat-test-store) for complete version requirements. +::: ## 3. Using RevenueCat's Purchases SDK @@ -123,18 +91,17 @@ If you have a user authentication system in your app, you can provide a user ide ### Present a Paywall -At this point, you're ready to present a paywall to your users. If you skipped the paywall setup earlier, that's okay! The SDK will display a default, non-customized paywall. If you want to customize a paywall first, head back up to the [Build and Design Your Paywall](#build-and-design-your-paywall) section. +The SDK will automatically fetch your configured Offerings and retrieve product information from your Test Store or connected stores (Apple, Google, Amazon). You can present a paywall using RevenueCat's pre-built UI or build your own. -The SDK will automatically fetch the [configured Offerings](/getting-started/entitlements#offerings) and retrieve the product information from Apple, Google, or Amazon. Thus, available products will already be loaded when customers launch your paywall. +**Option A: Use RevenueCat Paywalls** (Recommended) -Presenting a paywall varies depending on your platform. See [Displaying Paywalls](/tools/paywalls/displaying-paywalls) to see in-depth examples for each platform. +RevenueCat provides customizable paywall templates that you can configure remotely. See [Creating Paywalls](/tools/paywalls/creating-paywalls) to design your paywall, then [Displaying Paywalls](/tools/paywalls/displaying-paywalls) for platform-specific implementation. {} -
-
+**Option B: Build Your Own** -_Want to display your products manually? See [Displaying Products](/getting-started/displaying-products)._ +If you prefer full control, manually display products and handle purchases. See [Displaying Products](/getting-started/displaying-products) and [Making Purchases](/getting-started/making-purchases). #### SDK not fetching products or offerings? @@ -144,13 +111,24 @@ If you're running into this error, please see our [community post](https://commu ### Make a Purchase -Once your paywall is presented, select one of your products to make a purchase. The SDK will handle the purchase flow automatically and send the purchase information to RevenueCat. The RevenueCat SDK will automatically handle sandbox vs. production environments. +Once your paywall is presented, select one of your products to make a purchase. The SDK will handle the purchase flow automatically and send the purchase information to RevenueCat. + +**Testing with Test Store:** + +- Test Store purchases work immediately without any additional setup +- They behave just like real subscriptions in your app +- No real money is charged +- Perfect for development and testing your integration + +**Testing with real stores:** -Each platform requires slightly different configuration steps to test in sandbox. See [Sandbox Testing](/test-and-launch/sandbox) for more information. +- The RevenueCat SDK automatically handles sandbox vs. production environments +- Each platform requires slightly different configuration steps to test in sandbox +- See [Sandbox Testing](/test-and-launch/sandbox) for platform-specific instructions When the purchase is complete, you can find the purchase associated to the customer in the [RevenueCat dashboard](/dashboard-and-metrics/customer-profile). You can [search for the customer](/dashboard-and-metrics/customer-lists#find-an-individual-customer) by their App User ID that you configured, or by the automatically assigned `$RCAnonymousID` that you'll find in your logs. -**Note:** RevenueCat **_always_** validates transactions with the respective store. The dashboard will only reflect purchases that have been successfully validated by the store. +**Note:** RevenueCat **_always_** validates transactions. Test Store purchases are validated by RevenueCat; real store purchases are validated by the respective platform (Apple, Google, etc.). Additionally, the SDK will automatically update the customer's `CustomerInfo` object with the new purchase information. This object contains all the information about the customer's purchases and subscriptions. @@ -280,8 +258,7 @@ To download more complete examples of integrating the SDK, head over to our samp ## Next Steps -- If you haven't already, make sure your products are configured correctly by checking out our [guide on entitlements ](/getting-started/entitlements). -- If you want to use your own user identifiers, read about [setting app user IDs ](/customers/user-ids). -- If you're moving to RevenueCat from another system, see our guide on [migrating your existing subscriptions ](/migrating-to-revenuecat/migrating-existing-subscriptions). -- Once you're ready to test your integration, you can follow our guides on [testing and debugging ](/test-and-launch/debugging). -- If you qualify for the App Store Small Business Program, check out our guide on [how to apply and inform RevenueCat ](/platform-resources/apple-platform-resources/app-store-small-business-program) +- If you want to use your own user identifiers, read about [setting app user IDs](/customers/user-ids). +- Once you're ready to test your integration, follow our guides on [testing and debugging](/test-and-launch/debugging). +- If you're moving to RevenueCat from another system, see our [migration guide](/migrating-to-revenuecat/migrating-existing-subscriptions). +- If you qualify for the App Store Small Business Program, check out our [guide on how to apply](/platform-resources/apple-platform-resources/app-store-small-business-program). diff --git a/docs/offerings/products-overview.md b/docs/offerings/products-overview.md index fa8e3f00a..c7b2ddb97 100644 --- a/docs/offerings/products-overview.md +++ b/docs/offerings/products-overview.md @@ -6,13 +6,32 @@ excerpt: Use Entitlements and Offerings to organize and display products hidden: false --- -Products are the individual SKUs that users actually purchase from your app. The stores (Apple, Google, Stripe, etc.) process these SKUs and charge the user. +Products are the individual SKUs that users actually purchase from your app. You can create products in two ways: + +- **Test Store products** - Create directly in RevenueCat for testing (no store setup required) +- **Real store products** - Products from Apple, Google, Stripe, etc. that process real payments RevenueCat Offerings are a way to organize and display products to users. You can read more about Offerings [here](/offerings/overview). -## Store Configuration +## Test Store Products + +Create Test Store products directly in RevenueCat for development and testing—no app store setup required. + +To create a Test Store product: + +1. Go to **Products** in the **Product catalog** section +2. Click **+ New product** +3. Select **Test Store** as the store +4. Enter a product identifier and configure pricing +5. Click **Save** + +:::tip +Use Test Store during development. When ready for production, create real store products. See [Sandbox Testing](/test-and-launch/sandbox). +::: + +## Real Store Products -No matter how you choose to use RevenueCat, you'll need to first have products set up in the stores. This is done outside of RevenueCat, and where you set things like price, duration, and free trials. If you've never set up products before or need a refresher (or tips and tricks) check out these guides: +For production, set up products in the real stores (Apple, Google, Stripe, etc.). This is where you configure price, duration, and free trials: - **[iOS / App Store Connect ](/getting-started/entitlements/ios-products)** - **[Android / Google Play Console ](/getting-started/entitlements/android-products)** @@ -26,9 +45,9 @@ RevenueCat supports free trials, promotional offers, and other product configura You can read more about these product configuration options [here](/subscription-guidance/subscription-offers). -## Add Products to RevenueCat +## Import Products to RevenueCat -After your products are set up in the stores, you'll need to set up a 1-to-1 mapping of the products in RevenueCat as well. +After setting up products in the real stores, import them into RevenueCat to create a 1-to-1 mapping. :::info Automatic Tracking If a user purchases a product that has not been set up in RevenueCat, the transaction will still be tracked in RevenueCat, and the product will be automatically created in RevenueCat. @@ -67,6 +86,6 @@ Product display names must be unique within an app. It's a good practice to incl ## Next steps -If you've added your products in the dashboard, it's time to create an Entitlement. +After adding products (Test Store or real store), organize them with Entitlements and Offerings. diff --git a/docs/projects/configuring-products.mdx b/docs/projects/configuring-products.mdx new file mode 100644 index 000000000..aa5781fca --- /dev/null +++ b/docs/projects/configuring-products.mdx @@ -0,0 +1,106 @@ +--- +title: Configuring Products +slug: configuring-products +excerpt: Set up products, entitlements, and offerings to start testing purchases +hidden: false +--- + +After creating your RevenueCat project, you need to configure what users can purchase and what access they receive. This takes about 5-10 minutes. + +## Overview + +RevenueCat uses three concepts to manage purchases: + +1. **Products** - The individual items users purchase (e.g., "Monthly Premium") +2. **Entitlements** - The access level users receive (e.g., "premium") +3. **Offerings** - How you group and display products in your app (optional but recommended) + +**The flow:** User purchases a **Product** → Unlocks an **Entitlement** → You check the entitlement to grant access. + +## 1. Choose Your Product Type + +Your project comes with a **Test Store** automatically configured. This lets you create products and test purchases immediately—no App Store or Google Play account required. + +### For Development: Use Test Store + +- Create products directly in RevenueCat +- Test purchases work instantly +- No real money charged +- Perfect for building and testing your integration + +### For Production: Configure Real Stores + +Before submitting to app stores, you must configure products in: + +- [Apple App Store Connect](/getting-started/entitlements/ios-products) +- [Google Play Console](/getting-started/entitlements/android-products) +- [Amazon Appstore](/getting-started/entitlements/amazon-product-setup) +- [Stripe](/getting-started/entitlements/stripe-products) or [Paddle](/getting-started/entitlements/paddle-products) for web + +Then import those products into RevenueCat. + +## 2. Create Products + +### With Test Store (Quickest Start) + +1. Go to your project dashboard +2. Navigate to **Product catalog → Products** +3. Select the **Test Store** tab +4. Click **+ New** to create a product +5. Configure the product details (name, identifier, price, duration) + +### With Real Stores + +1. Create products in your store (Apple, Google, Amazon, Stripe, Paddle) +2. In RevenueCat, go to **Product catalog → Products** +3. Select your store's tab +4. Import or manually add the product using the store's product identifier + +[Learn more about products →](/offerings/products-overview) + +## 3. Create Entitlements + +Entitlements represent the access levels in your app (like "premium", "pro", or "gold"). + +1. Navigate to **Product catalog → Entitlements** +2. Click **+ New** +3. Enter an identifier (e.g., "premium") - you'll use this in your code +4. Add a description + +Most apps need just one entitlement. Create multiple only if you have different tiers (e.g., "gold" vs "platinum"). + +[Learn more about entitlements →](/getting-started/entitlements) + +## 4. Attach Products to Entitlements + +Link your products to entitlements to define what purchases unlock. + +1. In the Entitlements page, click on your entitlement +2. Click **Attach** in the Products section +3. Select the product(s) that should unlock this entitlement +4. Save + +Now when a user purchases that product, they'll automatically have access to the entitlement. + +## 5. Create Offerings (Recommended) + +Offerings let you group products and change what's displayed without app updates. Required if you want to use RevenueCat Paywalls, Experiments, or Targeting. + +1. Navigate to **Product catalog → Offerings** +2. Click **+ New** +3. Give it an identifier (e.g., "default") +4. Add Packages—these group equivalent products across platforms (e.g., monthly subscriptions from iOS and Android) + +The offering marked as "default" is automatically returned as `currentOffering` in the SDK. + +[Learn more about offerings →](/offerings/overview) + +## What's Next + +With your products configured, you're ready to: + +1. **[Install the SDK](/getting-started/installation)** - Add RevenueCat to your app +2. **[Create a Paywall](/tools/paywalls)** - Design how users see your products +3. **[Make your first test purchase](/getting-started/quickstart#make-a-purchase)** - Verify everything works + +Or jump straight to the [SDK Quickstart →](/getting-started/quickstart) diff --git a/docs/projects/connect-a-store.md b/docs/projects/connect-a-store.md index 6ba75d99b..47b39ebe2 100644 --- a/docs/projects/connect-a-store.md +++ b/docs/projects/connect-a-store.md @@ -5,7 +5,9 @@ slug: connect-a-store excerpt: Connect supported apps and web providers to your project --- -Once you've created a [project](/projects/overview), you'll need to connect it to the stores and payment providers you want to support and set up [Server Notifications](/platform-resources/server-notifications). After you've connected your app, you can import your products from the stores to start configuring your offerings. +Each [project](/projects/overview) comes with a Test Store where you can create products, configure offerings, and test the complete purchase flow—without connecting to any app store or payment provider. + +When you're ready to submit your app for review, you'll need to connect it to the real stores and payment providers you want to support and set up [Server Notifications](/platform-resources/server-notifications). After you've connected your app, you can import your products from the stores to start configuring your offerings. Add an **app config** or **web config** in the _Apps & providers_ section of your app settings. @@ -13,6 +15,10 @@ Add an **app config** or **web config** in the _Apps & providers_ section of you ![Add Web Configuration](/docs_images/projects/add-web-platform.png) +:::warning Switching from Test Store to Production +If you've been using Test Store during development, remember to switch from your Test Store API key to your platform-specific API key before submitting to app review. See [Launch Checklist](/test-and-launch/launch-checklist). +::: + ## Add a Configuration RevenueCat supports a wide range of stores and payment providers. diff --git a/docs/projects/projects-overview.mdx b/docs/projects/projects-overview.mdx index 3e43fdeff..44568ec8f 100644 --- a/docs/projects/projects-overview.mdx +++ b/docs/projects/projects-overview.mdx @@ -13,6 +13,8 @@ Within a project, you can also configure integrations like [Webhooks](/integrati To create a Project, click the **'+ Create new project'** button in the Projects dropdown panel at the top of the RevenueCat dashboard. +Each created Project comes with a Test Store which enables you to configure your Products and Paywalls and test purchases without the need for Apple, Google or Stripe accounts. + You can customize your project by setting a name as well as your global [restore behavior](/getting-started/restoring-purchases) for the apps in your Project. ![Screenshot](/docs_images/projects/project-settings.png) @@ -72,6 +74,6 @@ If you are changing the App Store Connect or Google Developer account, this will ## Next steps -If you've configured your project in the dashboard, it's time to connect to a store by adding your app. +Now that you've created your project, configure your products, entitlements, and offerings to start testing purchases. - + diff --git a/docs/projects/sandbox-access.md b/docs/projects/sandbox-access.md index cf7eb85d8..c6d27c02c 100644 --- a/docs/projects/sandbox-access.md +++ b/docs/projects/sandbox-access.md @@ -4,9 +4,18 @@ sidebar_label: Sandbox Testing Access slug: sandbox-access --- -When testing purchases in a sandbox environment, you may want to control whether those purchases grant access to entitlements or add to a customer's virtual currency balance. This setting gives you the flexibility to determine how sandbox behavior should be handled in your app during testing. +When testing purchases (Test Store or platform sandboxes), you may want to control whether those purchases grant access to entitlements or add to a customer's virtual currency balance. This setting gives you the flexibility to determine how non-production purchases should be handled in your app during testing. -If you're testing with real app user IDs or using test app user IDs that overlap with production ones, it can lead to unexpected behavior or data inconsistencies. This setting gives you control over whether sandbox purchases should grant [entitlements](/getting-started/entitlements) or [virtual currencies](/offerings/virtual-currency). +:::info Applies to all testing purchases +These settings control whether **non-production purchases** grant entitlements and virtual currency. This includes: + +- **Test Store purchases** (RevenueCat's testing environment) +- **Platform sandbox purchases** (Apple Sandbox, Google Play testing, Amazon sandbox, etc.) + +Both types of testing purchases are treated the same by these settings. +::: + +If you're testing with real app user IDs or using test app user IDs that overlap with production ones, it can lead to unexpected behavior or data inconsistencies. This setting gives you control over whether non-production purchases should grant [entitlements](/getting-started/entitlements) or [virtual currencies](/offerings/virtual-currency). ![Sandbox Testing Settings](/docs_images/projects/sandbox-testing-settings.png) @@ -14,19 +23,19 @@ You can configure this setting in the **General** tab of your project settings: ### Allow testing entitlements and virtual currency for -- **Anybody** _(default)_: All sandbox purchases will grant access to entitlements and add virtual currency, as configured. This is the default behavior and is recommended for early development or internal QA testing. -- **Allowed App User IDs only**: Only app user IDs that you’ve added to your allowlist will receive entitlements or virtual currency from sandbox purchases. You can add multiple IDs separated by spaces or line breaks. This may be useful when running restricted tests (e.g: Google Play closed testing). -- **Nobody**: No sandbox purchases will grant entitlements or virtual currency. Use this option if you want to prevent all testing from affecting entitlement access or virtual currency balances. +- **Anybody** _(default)_: All **non-production purchases** (Test Store and platform sandbox) will grant access to entitlements and add virtual currency, as configured. This is the default behavior and is recommended for early development or internal QA testing. +- **Allowed App User IDs only**: Only app user IDs that you've added to your allowlist will receive entitlements or virtual currency from **non-production purchases**. You can add multiple IDs separated by spaces or line breaks. This may be useful when running restricted tests (e.g: Google Play closed testing). +- **Nobody**: No **non-production purchases** will grant entitlements or virtual currency. Use this option if you want to prevent all testing from affecting entitlement access or virtual currency balances. -### Restricting Sandbox Access +### Restricting Testing Access -If you update this setting to restrict access (e.g., changing from Anybody → Allowed App User IDs or Anybody → Nobody), here’s what to expect: +If you update this setting to restrict access (e.g., changing from Anybody → Allowed App User IDs or Anybody → Nobody), here's what to expect: -- ✅ Sandbox purchases will still be recorded. - - All sandbox purchases continue to be processed and appear in RevenueCat, regardless of this setting. +- ✅ Non-production purchases will still be recorded. + - All Test Store and platform sandbox purchases continue to be processed and appear in RevenueCat, regardless of this setting. - ✅ Only customers who meet the new setting will receive access and grants going forward. - Entitlements and virtual currency will only be granted to customers who match the current access level you've configured. - 🔁 Previously granted entitlements will be removed. - - If a customer no longer qualifies under the updated setting, any active entitlements previously granted from sandbox purchases will be automatically removed. + - If a customer no longer qualifies under the updated setting, any active entitlements previously granted from non-production purchases will be automatically removed. - 💰 Virtual currency already granted will remain. - - If a sandbox purchase previously added virtual currency to a customer's balance, that currency will not be removed, even if the customer no longer qualifies under the new setting. + - If a non-production purchase previously added virtual currency to a customer's balance, that currency will not be removed, even if the customer no longer qualifies under the new setting. diff --git a/docs/subscription-guidance/managing-subscriptions.mdx b/docs/subscription-guidance/managing-subscriptions.mdx index f1c3fd3da..259fe74b1 100644 --- a/docs/subscription-guidance/managing-subscriptions.mdx +++ b/docs/subscription-guidance/managing-subscriptions.mdx @@ -135,5 +135,5 @@ import kt2 from "@site/code_blocks/subscription-guidance/managing-subscriptions_ /> :::warning Deleting a User -Deleting a user from RevenueCat **WILL NOT** cancel their subscription. The user can still trigger the [Restore Purchases](/getting-started/making-purchases#restoring-purchases) method to re-sync their transactions with RevenueCat servers. +Deleting a user from RevenueCat **WILL NOT** cancel their subscription. The user can still trigger the [Restore Purchases](/getting-started/restoring-purchases) method to re-sync their transactions with RevenueCat servers. ::: diff --git a/docs/test-and-launch/launch-checklist.mdx b/docs/test-and-launch/launch-checklist.mdx index ce02f7cc2..4898446e3 100644 --- a/docs/test-and-launch/launch-checklist.mdx +++ b/docs/test-and-launch/launch-checklist.mdx @@ -8,6 +8,19 @@ hidden: false This document contains a checklist of things to consider before launching subscriptions in your app to production. +:::danger 🚨 CRITICAL: Replace Test Store API Key Before Submission +**You MUST replace your Test Store API key with the correct platform-specific API key (iOS, Android, etc.) before submitting your app for review.** + +If you've been testing with the Test Store during development: + +1. Go to **Project Settings > API keys** in the RevenueCat dashboard +2. Copy the correct platform-specific API key (iOS for App Store, Android for Google Play) +3. Update your app configuration to use the platform-specific API key for release builds +4. **Never submit an app configured with a Test Store API key to app review** + +Using a Test Store API key in production will crash your app. See [Configuring SDK](/getting-started/configuring-sdk#switching-between-test-store-and-real-stores) for details on managing API keys across environments. +::: + ## 1. Know your plan limits | Plan Limits | iOS | Android | @@ -34,6 +47,10 @@ This document contains a checklist of things to consider before launching subscr | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- | | Before releasing, make sure that all agreements and tax forms have been signed and that banking information has been added as this is required to fetch products correctly. Regularly monitor these for updates in agreements and tax forms from the respective stores in order to ensure acceptance and the seamless retrieval of products. | ✅ | ✅ | +| **Test with real store sandbox (not Test Store)** | iOS | Android | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ------- | +| Before launch, test purchases using your platform-specific API key with real store products in the platform's sandbox environment (Apple Sandbox/Google testing). This verifies your complete integration works end-to-end with real stores, not just Test Store. See [Sandbox Testing](/test-and-launch/sandbox) for platform-specific instructions. If you only tested with Test Store during development, this step is critical to catch any real store integration issues before submission. | ✅ | ✅ | + | All products are available | iOS | Android | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- | | Verify that all of your products are being fetched correctly by RevenueCat. If any product is unavailable, there may be a [configuration issue](https://www.revenuecat.com/blog/engineering/app-store-connect-in-app-purchase-guide/). | ✅ | ✅ | @@ -62,23 +79,27 @@ This document contains a checklist of things to consider before launching subscr ## 5. Prepare release -| Store description | iOS | Android | +| **Replace Test Store API key with platform-specific API key** | iOS | Android | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ------- | +| **CRITICAL:** If you used Test Store during development, you MUST switch to your platform-specific API key (iOS/Android) for release builds. Find your production API keys in **Project Settings > API keys**. Never submit an app with a Test Store API key—real purchases will not work. | ✅ | ✅ | + +| **Store description** | iOS | Android | | ---------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- | | Include [disclosure of auto-renewing subscription details](https://www.revenuecat.com/blog/schedule-2-section-3-8-b/) in your app description. | ✅ | ❌ | -| App Privacy | iOS | Android | +| **App Privacy** | iOS | Android | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- | | As of December 8, 2020, Apple requires thorough [App Privacy](/platform-resources/apple-platform-resources/apple-app-privacy) disclosures for third-parties, including RevenueCat. By April 2022, Google requires a [Data Safety](/platform-resources/google-platform-resources/google-plays-data-safety) disclosure for all apps on the platform. | ✅ | ✅ | -| Phased rollout | iOS | Android | +| **Phased rollout** | iOS | Android | | ---------------------------------------------------------------------------------------------------------------------- | --- | ------- | | Choose a staged release option so you can monitor, and halt, a rollout on a fraction of users if there's any problems. | ✅ | ✅ | -| Choose to manually release app | iOS | Android | +| **Choose to manually release app** | iOS | Android | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------- | | On iOS, if your app contains new products, choose to manually release the version and wait ~24 hours after your app is "Cleared for Sale" to release publicly. This is because it sometimes takes new products ~24 hours to propagate throughout the App Store. | ✅ | ❌ | -| IDFA guidelines | iOS | Android | +| **IDFA guidelines** | iOS | Android | | ------------------------------------------------------------------------------------------------------------------------------ | --- | ------- | | If you're using an attribution integration, ensure your app complies with IDFA usage guidelines by disclosing the use of IDFA. | ✅ | ❌ | diff --git a/docs/test-and-launch/sandbox.mdx b/docs/test-and-launch/sandbox.mdx index 8e0ca5df1..267a9e1d1 100644 --- a/docs/test-and-launch/sandbox.mdx +++ b/docs/test-and-launch/sandbox.mdx @@ -5,27 +5,131 @@ excerpt: Making in-app purchases from a test account hidden: false --- -You don't need to make real purchases in order to test your subscriptions. You can make sure your subscriptions have been implemented correctly by using the sandbox environments. These environments will generally behave as the real stores, without incurring any costs. +You don't need to make real purchases in order to test your subscriptions. RevenueCat provides two ways to test your implementation without incurring any costs: -RevenueCat will automatically detect the environment (production vs. sandbox) in which a purchase occurs, so no additional configuration is required in RevenueCat to test in sandbox. +1. **Test Store** - RevenueCat's built-in testing environment that works immediately without platform setup +2. **Platform Sandboxes** - Apple, Google, and Amazon's sandbox environments for testing real store integrations + +Both approaches let you verify your purchase flow works correctly before going to production. + +## Test Store vs Platform Sandboxes + +### Test Store + +Test Store is RevenueCat's built-in testing environment, automatically provisioned with every new project. It's the fastest way to start testing purchases. + +**Benefits:** + +- ✅ **No platform accounts needed** - Test without App Store Connect or Google Play Console access +- ✅ **Works immediately** - Automatically provisioned with every project +- ✅ **Perfect for early development** - Rapid iteration without platform delays +- ✅ **Works everywhere** - Ideal for Expo, web apps, and environments without native store APIs +- ✅ **Accurate metadata** - Product names, prices, and descriptions are exactly as configured in RevenueCat + +**Limitations:** + +- ⚠️ **Doesn't test platform-specific features** - Won't catch issues with StoreKit behavior, billing grace periods, or platform edge cases +- ⚠️ **Requires separate API key** - Must switch to platform-specific API key before production (see [Launch Checklist](/test-and-launch/launch-checklist)) + +### Platform Sandboxes (Apple/Google/Amazon) + +Platform sandboxes are testing environments provided by Apple, Google, and Amazon that simulate real store purchases. + +**Benefits:** + +- ✅ **Tests complete end-to-end integration** - Validates your app works with real store APIs +- ✅ **Tests platform-specific features** - Subscription renewals, grace periods, billing retry, etc. +- ✅ **Required before launch** - Essential final step before production deployment + +**Limitations:** + +- ⚠️ **Requires platform accounts** - Need App Store Connect or Google Play Console access +- ⚠️ **More complex setup** - Requires product configuration in platform dashboards +- ⚠️ **Metadata inconsistencies** - Prices and descriptions may not be accurate (see [Sandbox Limitations](#sandbox-limitations) below) + +## Recommended Testing Workflow + +For the best testing experience, follow this workflow: + +1. **Start with Test Store** (Development) + - Use Test Store during initial development to build and test your purchase flow, paywall display, and entitlement logic + - Iterate quickly without waiting for platform approvals or configuration + +2. **Test with Platform Sandboxes** (Pre-Launch) + - Before submitting to app review, switch to your platform-specific API key + - Test purchases in Apple Sandbox, Google Play testing, or Amazon sandbox + - Verify the complete end-to-end integration works with real stores + +3. **Deploy to Production** (Launch) + - Use platform-specific API key (never Test Store API key!) + - Deploy with real store products configured in your offerings + +## Testing with RevenueCat Test Store + +:::info SDK Version Requirements +Test Store requires the following minimum SDK versions: + +| Platform | Minimum Version | +| ------------ | --------------- | +| iOS | 5.43.0 | +| Android | 9.9.0 | +| Flutter | 9.8.0 | +| React Native | 9.5.4 | +| Capacitor | 11.2.6 | +| Cordova | 7.2.0 | +| Unity | 8.3.0 | +| KMP | 2.2.2 | +| Web (JS) | 1.15.0 | + +Older SDK versions will not support Test Store products. +::: + +Test Store works automatically with the SDK—no additional configuration required beyond using your Test Store API key. Simply: + +1. Configure test products in your RevenueCat dashboard +2. Add products to offerings +3. Initialize the SDK with your Test Store API key +4. Make test purchases in your app + +Test purchases behave like real subscriptions: they update `CustomerInfo`, trigger entitlements, and appear in your RevenueCat dashboard. + +:::tip Control test purchase behavior +You can control whether test purchases (both Test Store and platform sandboxes) grant entitlements using [Sandbox Testing Access](/projects/sandbox-access) settings. This is useful for restricting testing to specific app user IDs. +::: + +:::tip +See [Configuring SDK](/getting-started/configuring-sdk#testing-with-test-store) for details on using Test Store API keys and switching to production keys. +::: + +## Testing with Platform Sandboxes + +RevenueCat automatically detects the environment (production vs. sandbox) in which a purchase occurs, so no additional configuration is required in RevenueCat to test in platform sandboxes. + +Before launching to production, test with your platform's sandbox environment: - **[Apple App Store Sandbox Testing](/test-and-launch/sandbox/apple-app-store)** - **[Google Play Store Sandbox Testing](/test-and-launch/sandbox/google-play-store)** - **[Amazon Appstore Sandbox Testing](/test-and-launch/sandbox/amazon-store-sandbox-testing)** - **[RevenueCat Web Billing Sandbox Testing](/web/web-billing/testing)** -## Viewing Sandbox Data +## Viewing Non-Production Data + +Clicking the sandbox data toggle below the Overview metrics will change the Overview metrics to report non-production purchases (both Test Store purchases and platform sandbox purchases). To go back to production purchases you will need to toggle this off. + +There's no concept of a sandbox or production _user_ in RevenueCat, since the same App User Id can have both production and non-production receipts. Because of this, **the 'Sandbox data' toggle will not affect 'Installs' or 'Active User' cards**. -Clicking the sandbox data toggle below the Overview metrics will change the Overview metrics to report sandbox purchases. To go back to production purchases you will need to toggle this off. There's no concept of a sandbox or production _user_ in RevenueCat, since the same App User Id can have both production and sandbox receipts. Because of this, **the 'Sandbox data' toggle will not affect 'Installs' or 'Active User' cards**. +## Platform Sandbox Limitations -## Sandbox Limitations +:::info These limitations apply to platform sandboxes only +Test Store does not have these limitations—product metadata (names, prices, descriptions) in Test Store is always accurate as configured in RevenueCat. +::: -In general, the sandbox environments behave nearly identical to the production environments. That being said, we recommend to test only **the flow of a purchase** in sandbox mode, and _not_ metadata-related tests on products. This is because: +In general, **platform sandbox environments** (Apple, Google, Amazon) behave nearly identical to the production environments. That being said, we recommend to test only **the flow of a purchase** in platform sandbox mode, and _not_ metadata-related tests on products. This is because: 1. Store APIs often do not return accurate prices across regions, including in TestFlight on iOS 2. Store APIs often do not return accurate names and descriptions for products -While the production environment is generally more stable than the sandbox environment, we're not able to provide support on why store APIs are not up to date at any given moment. For this reason, we recommend only testing the flow of a purchase in sandbox mode instead. For example: +While the production environment is generally more stable than the sandbox environment, we're not able to provide support on why store APIs are not up to date at any given moment. For this reason, we recommend only testing the flow of a purchase in platform sandbox mode instead. For example: 1. Initiate a purchase 2. Complete a purchase diff --git a/sidebars.ts b/sidebars.ts index e35ae5893..873303772 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -54,6 +54,7 @@ const projectsCategory = Category({ collapsed: false, items: [ Page({ slug: "projects/projects-overview" }), + Page({ slug: "projects/configuring-products" }), Page({ slug: "projects/connect-a-store" }), SubCategory({ label: "Connect Server Notifications",