[Apple Shared Secret] Added SK1 and SK2 context (#939)

* added apple shared secret context

* update as per PR comments

* update 2

* removed table

* one more tweak

Author: GuilhermeMota93

docs/service-credentials/itunesconnect-app-specific-shared-secret.mdx

@@ -6,9 +6,37 @@ excerpt: Getting your App Store Connect App-Specific Shared Secret
 hidden: false
 ---
 
-The App-Specific Shared Secret allows RevenueCat to connect with Apple on your behalf.
+The App-Specific Shared Secret is a unique authentication key that allows RevenueCat to securely communicate with Apple's servers on your behalf. This secret is **mandatory for receipt validation** when using **StoreKit 1**.
 
-## Setup
+:::warning
+StoreKit 1 is now deprecated by Apple. New apps are recommended to use **StoreKit 2**. See our [migration guide](/sdk-guides/ios-native-4x-to-5x-migration) for details.
+:::
+
+## StoreKit Version Requirements
+
+The App-Specific Shared Secret is required for **StoreKit 1** implementations. For **StoreKit 2** apps, you'll need an [In-App Purchase Key](/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration) instead.
+
+### StoreKit 2 (Recommended)
+
+- **Required**: [In-App Purchase Key](/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration) (comprising Issuer ID, Key ID, and Private Key)
+- **Use case**: Modern apps using iOS 15+ with RevenueCat SDK v5.0+
+- **Purpose**: Server-to-server communication with Apple's App Store Server API for validating transactions, managing subscriptions, and accessing detailed purchase information
+
+:::info
+The In-App Purchase Key is required for all in-app purchases (including subscriptions) when using StoreKit 2 and RevenueCat v5.0+. This key enables RevenueCat to securely access Apple's APIs and ensure accurate validation and reporting.
+:::
+
+### StoreKit 1
+
+- **Required**: App-Specific Shared Secret
+- **Use case**: Legacy apps, apps targeting iOS 15 or earlier
+- **Purpose**: Server-side receipt validation and subscription management for the traditional receipt-based flow
+
+## Setup (StoreKit 1 Only)
+
+:::warning
+This setup is only required for StoreKit 1 implementations. If you're using **StoreKit 2**, see [In-App Purchase Key Configuration](/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration) instead.
+:::
 
 ### 1. Generating an App-Specific Shared Secret
 
@@ -28,3 +56,20 @@ The App-Specific Shared Secret allows RevenueCat to connect with Apple on your b
 Enter the secret in your iOS app settings in the RevenueCat dashboard:
 
 ![Shared secret input](/docs_images/credentials/apple/shared-secret-input.png)
+
+## Troubleshooting
+
+### Receipt Validation Issues
+
+If you're experiencing server-side receipt validation failures, ensure you've configured the appropriate credentials for your StoreKit version:
+
+- **StoreKit 1**: App-Specific Shared Secret (this page)
+- **StoreKit 2**: [In-App Purchase Key](/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration)
+
+### Migration Context
+
+If you're migrating from StoreKit 1 to StoreKit 2, you'll need to:
+
+1. Update to [RevenueCat SDK v5.0+](/sdk-guides/ios-native-4x-to-5x-migration)
+2. Configure an [In-App Purchase Key](/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration)
+3. Remove the App-Specific Shared Secret configuration