feat: update openiap and support advancedCommerceDataIOS (#3112)

- Add advancedCommerceDataIOS support for StoreKit 2 attribution
tracking
- Support google/apple fields with android/ios fallback (deprecated)
- Deprecate requestPurchaseOnPromotedProductIOS
- Update documentation with new field names
- Add tests for new features
- Update OpenIAP to `apple 1.3.6`, `google 1.3.15`, `gql 1.3.6`

Closes #3106

Co-authored-by: hlus <kyshbogdan@gmail.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added iOS advancedCommerceData support and new Android billing-program
& external-link purchase helpers; promoted-product flow now returns a
boolean and supports a StoreKit 2 recommended listener + requestPurchase
path.
  * Examples now include type: 'in-app' in purchase calls.

* **Documentation**
* Updated examples and guides to use apple/google keys (ios/android
deprecated), subscriptionOffers guidance, and promoted-product
deprecation notes.

* **Tests**
* Added tests for apple/google precedence and iOS advancedCommerceData
propagation.

* **Chores**
  * Bumped platform/docs version metadata.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: hyochan

docs/blog/2025-12-24-release-14.6.3.md

@@ -0,0 +1,160 @@
+---
+slug: release-14.6.3
+title: Release 14.6.3 - Advanced Commerce Data & Platform Field Updates
+authors: [hyochan]
+tags: [release, ios, android, storekit2, attribution]
+description: React Native IAP 14.6.3 adds advancedCommerceData support for iOS attribution tracking and introduces the new google/apple platform fields with deprecation of ios/android fields.
+date: 2025-12-24
+---
+
+# React Native IAP 14.6.3
+
+14.6.3 brings **advancedCommerceData** support for iOS attribution tracking using StoreKit 2's `Product.PurchaseOption.custom`, along with updated platform field naming conventions and improved type safety for Billing Programs API.
+
+<!-- truncate -->
+
+## What's New
+
+### Advanced Commerce Data for iOS
+
+This release adds support for `advancedCommerceData` in iOS purchase requests, enabling attribution tracking through StoreKit 2's custom purchase options.
+
+```typescript
+import {requestPurchase} from 'react-native-iap';
+
+await requestPurchase({
+  request: {
+    apple: {
+      sku: 'com.example.premium',
+      advancedCommerceData: 'your-attribution-token-here',
+    },
+  },
+  type: 'in-app',
+});
+```
+
+This feature allows you to pass attribution data to Apple for analytics and marketing attribution purposes. The data is passed through StoreKit 2's `Product.PurchaseOption.custom` API.
+
+### New Platform Field Naming: `apple` and `google`
+
+We've introduced new, clearer platform field names for purchase requests:
+
+- `apple` (replaces `ios`)
+- `google` (replaces `android`)
+
+**Before (deprecated):**
+
+```typescript
+await requestPurchase({
+  request: {
+    ios: {sku: 'premium_monthly'},
+    android: {skus: ['premium_monthly']},
+  },
+  type: 'in-app',
+});
+```
+
+**After (recommended):**
+
+```typescript
+await requestPurchase({
+  request: {
+    apple: {sku: 'premium_monthly'},
+    google: {skus: ['premium_monthly']},
+  },
+  type: 'in-app',
+});
+```
+
+The old `ios` and `android` fields are still supported for backward compatibility but are now deprecated. We recommend migrating to the new field names.
+
+### Deprecated: `requestPurchaseOnPromotedProductIOS`
+
+The `requestPurchaseOnPromotedProductIOS()` function is now deprecated. In StoreKit 2, promoted products can be purchased directly via the standard `requestPurchase()` flow.
+
+**Before (deprecated):**
+
+```typescript
+// Old approach
+await requestPurchaseOnPromotedProductIOS();
+```
+
+**After (recommended):**
+
+```typescript
+import {promotedProductListenerIOS, requestPurchase} from 'react-native-iap';
+
+// Listen for promoted product taps
+promotedProductListenerIOS(async (product) => {
+  await requestPurchase({
+    request: {apple: {sku: product.id}},
+    type: 'in-app',
+  });
+});
+```
+
+This approach gives you more control over the purchase flow and integrates better with your existing error handling and UI logic.
+
+### Improved Type Safety for Billing Programs API
+
+The Billing Programs API functions now use `MutationField` types for better type inference:
+
+```typescript
+// These functions now have improved type safety
+isBillingProgramAvailableAndroid('external-offer');
+createBillingProgramReportingDetailsAndroid('external-offer');
+launchExternalLinkAndroid({...});
+```
+
+## OpenIAP Updates
+
+- **openiap-apple**: [1.3.2 → 1.3.7](https://github.com/hyodotdev/openiap/compare/apple-v1.3.2...apple-v1.3.7)
+- **openiap-google**: [1.3.14 → 1.3.16](https://github.com/hyodotdev/openiap/compare/google-v1.3.14...google-v1.3.16)
+- **openiap-gql**: [1.3.4 → 1.3.8](https://github.com/hyodotdev/openiap/compare/1.3.4...1.3.8)
+
+## Migration Guide
+
+### Platform Fields
+
+Update your purchase requests to use the new field names:
+
+```diff
+await requestPurchase({
+  request: {
+-   ios: {sku: 'product_id'},
+-   android: {skus: ['product_id']},
++   apple: {sku: 'product_id'},
++   google: {skus: ['product_id']},
+  },
+  type: 'in-app',
+});
+```
+
+### Promoted Products (iOS)
+
+Replace `requestPurchaseOnPromotedProductIOS()` with the listener pattern:
+
+```diff
+- await requestPurchaseOnPromotedProductIOS();
+
++ promotedProductListenerIOS(async (product) => {
++   await requestPurchase({
++     request: {apple: {sku: product.id}},
++     type: 'in-app',
++   });
++ });
+```
+
+## Installation
+
+```bash
+npm install react-native-iap react-native-nitro-modules
+# or
+yarn add react-native-iap react-native-nitro-modules
+# or
+bun add react-native-iap react-native-nitro-modules
+```
+
+Check out the [documentation](/docs/intro) for details on all features.
+
+Questions or feedback? Reach out via [GitHub issues](https://github.com/hyochan/react-native-iap/issues).

docs/docs/api/methods/core-methods.md

@@ -751,16 +751,29 @@ Returns: `Promise<Product | null>`
 
 ### requestPurchaseOnPromotedProductIOS()
 
+> **Deprecated**: In StoreKit 2, promoted products can be purchased directly via the standard `requestPurchase()` flow. Use `promotedProductListenerIOS` to receive the product ID when a user taps a promoted product, then call `requestPurchase()` with the received SKU directly.
+
 Initiates the purchase flow for the currently promoted product. Requires iOS 11+.
 
 ```ts
+// Recommended approach (StoreKit 2)
+import {promotedProductListenerIOS, requestPurchase} from 'react-native-iap';
+
+promotedProductListenerIOS(async (product) => {
+  await requestPurchase({
+    request: { apple: { sku: product.id } },
+    type: 'in-app',
+  });
+});
+
+// Legacy approach (deprecated)
 import {requestPurchaseOnPromotedProductIOS} from 'react-native-iap';
 
-await requestPurchaseOnPromotedProductIOS();
+const success = await requestPurchaseOnPromotedProductIOS();
 // Purchase result is delivered via purchase listeners/useIAP callbacks
 ```
 
-Returns: `Promise<void>`
+Returns: `Promise<boolean>` - `true` when the request triggers successfully
 
 ### getPendingTransactionsIOS()
 

docs/docs/api/use-iap.md

@@ -221,9 +221,10 @@ interface UseIAPOptions {
       // In hook: returns void. Listen via callbacks.
       await requestPurchase({
         request: {
-          ios: {sku: productId},
-          android: {skus: [productId]},
+          apple: {sku: productId},
+          google: {skus: [productId]},
         },
+        type: 'in-app',
       });
     } catch (error) {
       console.error('Purchase request failed:', error);
@@ -258,8 +259,8 @@ const buySubscription = async (subscriptionId: string) => {
   // 3) Request purchase with offers
   await requestPurchase({
     request: {
-      ios: {sku: subscriptionId},
-      android: {
+      apple: {sku: subscriptionId},
+      google: {
         skus: [subscriptionId],
         // Only include subscriptionOffers when offers are available
         ...(subscriptionOffers.length > 0 && {subscriptionOffers}),
@@ -283,12 +284,12 @@ const buySubscriptionWithOffer = async (
 ) => {
   await requestPurchase({
     request: {
-      ios: {
+      apple: {
         sku: subscriptionId,
         // Optional: apply promotional offer
         ...(discountOffer && {withOffer: discountOffer}),
       },
-      android: {skus: [subscriptionId]},
+      google: {skus: [subscriptionId]},
     },
     type: 'subs',
   });
@@ -436,16 +437,27 @@ const buySubscriptionWithOffer = async (
 
 #### requestPurchaseOnPromotedProductIOS
 
-- **Type**: `() => Promise<void>`
+- **Type**: `() => Promise<boolean>`
 - **Description**: Complete the purchase of a promoted product (iOS only)
-  > Removed in v2.9.0: `buyPromotedProductIOS`. Use `requestPurchaseOnPromotedProductIOS` instead.
+  > **Deprecated**: In StoreKit 2, promoted products can be purchased directly via the standard `requestPurchase()` flow. Use `promotedProductListenerIOS` to receive the product ID when a user taps a promoted product, then call `requestPurchase()` with the received SKU directly.
 - **Example**:
 
   ```tsx
+  // Recommended approach (StoreKit 2)
+  promotedProductListenerIOS(async (product) => {
+    await requestPurchase({
+      request: { apple: { sku: product.id } },
+      type: 'in-app',
+    });
+  });
+
+  // Legacy approach (deprecated)
   const completePurchase = async () => {
     try {
-      await requestPurchaseOnPromotedProductIOS();
-      console.log('Promoted product purchase completed');
+      const success = await requestPurchaseOnPromotedProductIOS();
+      if (success) {
+        console.log('Promoted product purchase completed');
+      }
     } catch (error) {
       console.error('Failed to purchase promoted product:', error);
     }
@@ -471,9 +483,10 @@ const IOSPurchaseExample = () => {
   const buyProduct = (product: Product) => {
     requestPurchase({
       request: {
-        ios: {sku: product.id},
-        android: {skus: [product.id]},
+        apple: {sku: product.id},
+        google: {skus: [product.id]},
       },
+      type: 'in-app',
     });
   };
 
@@ -507,9 +520,10 @@ const AndroidPurchaseExample = () => {
   const buyProduct = (product: Product) => {
     requestPurchase({
       request: {
-        ios: {sku: product.id},
-        android: {skus: [product.id]},
+        apple: {sku: product.id},
+        google: {skus: [product.id]},
       },
+      type: 'in-app',
     });
   };
 
@@ -579,9 +593,10 @@ const {requestPurchase} = useIAP({
      try {
        await requestPurchase({
          request: {
-           ios: {sku: productId},
-           android: {skus: [productId]},
+           apple: {sku: productId},
+           google: {skus: [productId]},
          },
+         type: 'in-app',
        });
      } finally {
        setLoading(false);

docs/docs/examples/purchase-flow.md

@@ -42,8 +42,8 @@ await fetchProducts({skus: ['product_id'], type: 'in-app'});
 // Purchase
 await requestPurchase({
   request: {
-    ios: {sku: 'product_id'},
-    android: {skus: ['product_id']},
+    apple: {sku: 'product_id'},
+    google: {skus: ['product_id']},
   },
   type: 'in-app',
 });

docs/docs/examples/subscription-flow.md

@@ -43,8 +43,8 @@ await fetchProducts({skus: ['premium_monthly'], type: 'subs'});
 const subscription = subscriptions[0];
 await requestPurchase({
   request: {
-    ios: {sku: 'premium_monthly'},
-    android: {
+    apple: {sku: 'premium_monthly'},
+    google: {
       skus: ['premium_monthly'],
       subscriptionOffers:
         subscription.subscriptionOfferDetailsAndroid?.map((offer) => ({
@@ -82,7 +82,7 @@ Requires explicit replacement with the current purchase token:
 ```tsx
 await requestPurchase({
   request: {
-    android: {
+    google: {
       skus: ['premium_yearly'],
       subscriptionOffers: [...],
       purchaseTokenAndroid: currentPurchase.purchaseToken, // Required

docs/docs/getting-started/setup-ios.md

@@ -74,7 +74,8 @@ function App() {
           key={product.id}
           onPress={() =>
             requestPurchase({
-              request: {ios: {sku: product.id}},
+              request: {apple: {sku: product.id}},
+              type: 'in-app',
             })
           }
         >
@@ -88,7 +89,7 @@ function App() {
 }
 ```
 
-> **💡 Cross-Platform Note:** This example shows iOS-specific usage with `sku`. For cross-platform compatibility, include both `sku` and `skus` in your request object. See the [Core Methods](/docs/api/methods/core-methods#requestpurchase) documentation for details.
+> **💡 Cross-Platform Note:** This example shows iOS-specific usage with `apple.sku`. For cross-platform compatibility, include both `apple` and `google` fields in your request object. The older `ios` and `android` fields are deprecated but still supported. See the [Core Methods](/docs/api/methods/core-methods#requestpurchase) documentation for details.
 
 ## Common Issues
 

docs/docs/guides/lifecycle.md

@@ -80,9 +80,10 @@ function ProductItem({productId}: {productId: string}) {
     try {
       await requestPurchase({
         request: {
-          ios: {sku: productId},
-          android: {skus: [productId]},
+          apple: {sku: productId},
+          google: {skus: [productId]},
         },
+        type: 'in-app',
       });
     } catch (error) {
       console.error('Purchase request failed:', error);