Skip to main content

2 posts tagged with "alternative-billing"

View All Tags

Release 14.4.12 - Alternative Billing Support

· 5 min read
Hyo
Hyo
React Native IAP Maintainer

React Native IAP Logo

React Native IAP 14.4.12 introduces comprehensive alternative billing support for both iOS and Android, empowering developers to use external payment systems alongside or instead of App Store and Google Play billing. This enables reduced platform fees and greater flexibility in monetization strategies while maintaining compliance with platform policies.

🚀 What's New​

Alternative Billing APIs​

This release adds full alternative billing functionality for both platforms:

Android​

  • Alternative Billing Only Mode: Exclusive use of your payment system
  • User Choice Billing Mode: Users choose between Google Play and your payment system
  • Three-step flow: check availability → show dialog → create reporting token
  • Automatic token generation for Google Play reporting (required within 24 hours)
  • Reduced service fees (4% reduction when using alternative billing)

iOS​

  • External Purchase Links: Redirect users to your external website (iOS 16.0+)
  • Purchase Notice Sheets: Required disclosure before external redirects (iOS 18.2+)
  • Expo config plugin support for automatic entitlement and Info.plist setup
  • Support for multiple URLs per country (up to 5 for music streaming apps)
  • Custom link regions and streaming-specific configurations

New APIs​

Android Alternative Billing​

import {
  initConnection,
  checkAlternativeBillingAvailabilityAndroid,
  showAlternativeBillingDialogAndroid,
  createAlternativeBillingTokenAndroid,
  userChoiceBillingListenerAndroid,
} from 'react-native-iap';

// Initialize with alternative billing mode
await initConnection({
  alternativeBillingModeAndroid: 'alternative-only', // or 'user-choice'
});

// 3-step alternative billing flow
const isAvailable = await checkAlternativeBillingAvailabilityAndroid();
const userAccepted = await showAlternativeBillingDialogAndroid();
const token = await createAlternativeBillingTokenAndroid(productId);

// User choice billing event listener
const subscription = userChoiceBillingListenerAndroid((details) => {
  console.log('User selected alternative billing');
  // Report to backend for Google Play compliance
});

iOS External Purchase​

import {
  canPresentExternalPurchaseNoticeIOS,
  presentExternalPurchaseNoticeSheetIOS,
  presentExternalPurchaseLinkIOS,
} from 'react-native-iap';

// Check availability (iOS 18.2+)
const canPresent = await canPresentExternalPurchaseNoticeIOS();

// Present notice sheet before external link
const noticeResult = await presentExternalPurchaseNoticeSheetIOS();

if (noticeResult.result === 'continue') {
  // Redirect to external purchase URL
  const result = await presentExternalPurchaseLinkIOS(
    'https://your-website.com/purchase',
  );
}

Expo Config Plugin Enhancement​

Automatic iOS alternative billing configuration:

// app.config.ts
export default {
  plugins: [
    [
      'react-native-iap',
      {
        iosAlternativeBilling: {
          // Required: Countries (ISO 3166-1 alpha-2)
          countries: ['kr', 'nl', 'de', 'fr'],

          // Optional: External URLs per country
          links: {
            kr: 'https://your-site.com/kr/checkout',
            nl: 'https://your-site.com/nl/checkout',
          },

          // Optional: Multiple URLs (iOS 17.5+, up to 5)
          multiLinks: {
            de: [
              'https://your-site.com/de/checkout',
              'https://your-site.com/de/offer',
            ],
          },

          // Optional: Custom regions (iOS 18.1+)
          customLinkRegions: ['de', 'fr', 'nl'],

          // Optional: Streaming regions (iOS 18.2+, music apps)
          streamingLinkRegions: ['at', 'de', 'fr', 'nl'],

          // Enable entitlements
          enableExternalPurchaseLink: true,
          enableExternalPurchaseLinkStreaming: false, // music apps only
        },
      },
    ],
  ],
};

The config plugin automatically adds:

  • Required entitlements (com.apple.developer.storekit.external-purchase, etc.)
  • Info.plist configuration (SKExternalPurchase, SKExternalPurchaseLink, etc.)
  • Proper URL validation and country code formatting

useIAP Hook Integration​

Alternative billing is fully integrated into the useIAP hook:

import {useIAP} from 'react-native-iap';

const {
  checkAlternativeBillingAvailabilityAndroid,
  showAlternativeBillingDialogAndroid,
  createAlternativeBillingTokenAndroid,
} = useIAP({
  // Android alternative billing configuration
  alternativeBillingModeAndroid: 'alternative-only',

  // User choice billing event handler
  onUserChoiceBillingAndroid: (details) => {
    console.log('User selected alternative billing');
    reportToBackend(details.externalTransactionToken);
  },
});

Example App​

A complete alternative billing example is now included in the example app:

Features​

  • Platform-specific flows (iOS external URLs vs. Android billing modes)
  • Billing mode switcher for Android (alternative-only vs. user-choice)
  • Real-time status updates and result display
  • Step-by-step guidance for compliance requirements
  • Deep linking recommendations for iOS

Access​

Run the example app and navigate to "Alternative Billing" from the home screen.

🔧 Technical Details​

Android Implementation​

  • Uses OpenIAP Google v1.2.12 with native alternative billing support
  • Auto-reconnection handling for billing service state
  • Proper token creation and reporting flow
  • User choice billing listener with event deduplication

iOS Implementation​

  • Leverages StoreKit External Purchase APIs (iOS 16.0+)
  • Support for new notice sheets (iOS 18.2+)
  • Proper entitlement management via config plugin
  • URL validation and country code handling

Type Safety​

All alternative billing APIs are fully typed with TypeScript:

  • AlternativeBillingModeAndroid: 'none' | 'alternative-only' | 'user-choice'
  • UserChoiceBillingDetails: Product list and external transaction token
  • ExternalPurchaseNoticeResultIOS: Notice sheet result with action
  • ExternalPurchaseLinkResultIOS: External link presentation result

📖 Documentation​

Comprehensive documentation added:

  • API Reference: Complete method signatures and examples in Core Methods
  • Type Definitions: All alternative billing types in Types
  • Expo Plugin Guide: Configuration examples and requirements
  • Example App: Working implementation for both platforms

⚠️ Important Notes​

Platform Approval Required​

Both platforms require special approval to use alternative billing:

  • iOS: External purchase entitlement approval from Apple
  • Android: Alternative billing approval in Google Play Console

Compliance Requirements​

  • iOS: URLs must use HTTPS, no query parameters, ≤1,000 characters
  • Android: External transaction tokens must be reported within 24 hours
  • Fees: Reduced platform fees apply (varies by platform and region)

Supported Regions​

  • iOS: US, EU, and approved countries (varies by feature)
  • Android: South Korea, India, EEA (varies by app type)

📦 Installation​

npm install react-native-iap@14.4.12
# or
yarn add react-native-iap@14.4.12
# or
bun add react-native-iap@14.4.12

For Expo projects, run npx expo prebuild after updating your config plugin.

🔗 References​

🙏 Acknowledgments​

This release builds on the alternative billing implementation from expo-iap, bringing the same powerful features to React Native CLI projects.

Try out alternative billing in 14.4.12 and let us know your feedback via GitHub issues!