14.7.7 - ExternalPurchaseCustomLink API (iOS 18.1+)

react-native-iap 14.7.7 adds support for Apple's ExternalPurchaseCustomLink API (iOS 18.1+) for apps using custom external purchase links.

New Features

ExternalPurchaseCustomLink API (iOS 18.1+)

The ExternalPurchaseCustomLink API enables apps to use custom external purchase links with token-based reporting to Apple. This is for apps that have been granted an entitlement to link out to external purchases.

Reference: ExternalPurchaseCustomLink Documentation

New APIs

isEligibleForExternalPurchaseCustomLinkIOS()

Check if your app is eligible to use the ExternalPurchaseCustomLink API.

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

const isEligible = await isEligibleForExternalPurchaseCustomLinkIOS();
if (isEligible) {
  // App can use custom external purchase links
}

getExternalPurchaseCustomLinkTokenIOS(tokenType)

Get an external purchase token for reporting to Apple's External Purchase Server API.

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

// For new customer acquisition
const acquisitionResult = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
if (acquisitionResult.token) {
  // Report to Apple's External Purchase Server API
  await reportToApple(acquisitionResult.token);
}

// For existing customer services
const servicesResult = await getExternalPurchaseCustomLinkTokenIOS('services');
if (servicesResult.token) {
  await reportToApple(servicesResult.token);
}

showExternalPurchaseCustomLinkNoticeIOS(noticeType)

Display the system disclosure notice sheet before linking out to external purchases.

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

const result = await showExternalPurchaseCustomLinkNoticeIOS('browser');
if (result.continued) {
  // User agreed to continue to external purchase
  // Now open your external purchase link
  await Linking.openURL('https://your-store.com/checkout');
} else {
  // User cancelled
}

Updated: presentExternalPurchaseNoticeSheetIOS()

Now returns externalPurchaseToken when user continues to external purchase.

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

const result = await presentExternalPurchaseNoticeSheetIOS();
if (result.result === 'continue') {
  console.log('Token:', result.externalPurchaseToken);
  // Report this token to Apple's External Purchase Server API
}

New Types

// Token types for getExternalPurchaseCustomLinkTokenIOS
type ExternalPurchaseCustomLinkTokenTypeIOS = 'acquisition' | 'services';

// Notice types for showExternalPurchaseCustomLinkNoticeIOS
type ExternalPurchaseCustomLinkNoticeTypeIOS = 'browser';

// Result of token retrieval
interface ExternalPurchaseCustomLinkTokenResultIOS {
  token?: string | null;
  error?: string | null;
}

// Result of showing notice
interface ExternalPurchaseCustomLinkNoticeResultIOS {
  continued: boolean;
  error?: string | null;
}

// Updated ExternalPurchaseNoticeResultIOS
interface ExternalPurchaseNoticeResultIOS {
  result: 'continue' | 'dismissed';
  externalPurchaseToken?: string | null; // New field
  error?: string | null;
}

Complete External Purchase Custom Link Flow

import {useEffect, useState} from 'react';
import {Linking, Platform} from 'react-native';
import {
  isEligibleForExternalPurchaseCustomLinkIOS,
  getExternalPurchaseCustomLinkTokenIOS,
  showExternalPurchaseCustomLinkNoticeIOS,
} from 'react-native-iap';

export function ExternalPurchaseCustomLink() {
  const [isEligible, setIsEligible] = useState(false);

  useEffect(() => {
    if (Platform.OS !== 'ios') return;

    isEligibleForExternalPurchaseCustomLinkIOS().then(setIsEligible);
  }, []);

  const handleExternalPurchase = async () => {
    // Step 1: Show disclosure notice
    const noticeResult = await showExternalPurchaseCustomLinkNoticeIOS('browser');
    if (!noticeResult.continued) {
      console.log('User cancelled');
      return;
    }

    // Step 2: Get token for reporting
    const tokenResult = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
    if (tokenResult.error) {
      console.error('Failed to get token:', tokenResult.error);
      return;
    }

    // Step 3: Open external purchase link
    await Linking.openURL('https://your-store.com/checkout');

    // Step 4: After purchase completes, report to Apple
    if (tokenResult.token) {
      // This is a placeholder for your own server-side logic to report the token
      // to Apple's External Purchase Server API.
      // await reportExternalPurchaseToApple(tokenResult.token);
    }
  };

  if (!isEligible) return null;

  return (
    <Button title="Purchase on Web" onPress={handleExternalPurchase} />
  );
}

OpenIAP Updates

Package	Version
openiap-gql	1.3.16
openiap-apple	1.3.14
openiap-google	1.3.27

Installation

npm install react-native-iap@14.7.7
# or
yarn add react-native-iap@14.7.7

References

• Apple ExternalPurchaseCustomLink Documentation
• OpenIAP Release Notes

Questions or feedback? Reach out via GitHub issues.