Add React Native preload observability

[markmur]

What changes are you making?

Adds preload observability to the React Native package using the native APIs already available in the pinned Swift and Android 4.0.0-alpha.4 SDKs.

• exposes preload(checkoutUrl, {onStateChange}) and a subscription with state and remove()
• keeps one process-wide native event subscription and routes updates by request ID
• automatically replaces the previous observer on repeated preload calls
• serializes the native preload states and failure reasons consistently across iOS and Android
• documents a cart-screen integration for entry, quantity changes, and item removal
• updates public API reports and bridge/unit tests

Removing a subscription stops observation only. Cache invalidation remains explicit through invalidate().

API example

const subscription = checkout.preload(checkoutUrl, {
  onStateChange(state) {
    if (state.type === 'ready') {
      reportPreloadReady();
    }

    if (state.type === 'failed') {
      reportPreloadFailure(state.reason, state.statusCode);
    }
  },
});

// Stop callbacks without invalidating the preloaded checkout.
subscription.remove();

The callback options object does not need to be memoized. Calling preload(...) again replaces the previous observer, while the module retains one process-wide native event subscription.

Recommended cart integration

Preload when the buyer enters the cart and after successful cart mutations. Use the cart returned by the Storefront API mutation so the latest checkout URL is always supplied.

import type {CheckoutPreloadSubscription} from '@shopify/checkout-kit-react-native';

let preloadSubscription: CheckoutPreloadSubscription | undefined;

function preloadCart(cart: Cart) {
  if (!cart.checkoutUrl || cart.totalQuantity === 0) {
    checkout.invalidate();
    return;
  }

  preloadSubscription = checkout.preload(cart.checkoutUrl, {
    onStateChange(state) {
      reportPreloadState(state);
    },
  });
}

function onCartScreenEntered(cart: Cart) {
  preloadCart(cart);
}

async function changeQuantity(lineId: string, quantity: number) {
  const updatedCart = await updateCartLine(lineId, quantity);
  preloadCart(updatedCart);
}

async function removeItem(lineId: string) {
  const updatedCart = await removeCartLine(lineId);
  preloadCart(updatedCart);
}

function onCartScreenDisposed() {
  preloadSubscription?.remove();
}

Consumers should not block checkout on ready or automatically retry failed or expired states. A normal present(checkoutUrl) remains the fallback when preload is unavailable or incomplete.

---

Before you merge

• I have added tests to support my implementation
• I have read and agree with the Contribution Guidelines
• I have read and agree with the Code of Conduct
• I have updated the relevant React Native README

Swift, Android, and protocol release checklists are not applicable.

[github-actions]

React Native — Coverage Report

Lines	Statements	Branches	Functions
	90.97% (363/399)	87.29% (213/244)	100% (92/92)

[github-actions]

Package Size

Platform	Artifact	Base	Head	Delta
React Native	npm tarball	101.6 KiB	106.8 KiB	+5.2 KiB

React Native file breakdown

File	Base	Head	Delta
node_modules/@shopify/checkout-kit-protocol/src/generated/Models.ts	85.4 KiB	85.4 KiB	0 B
node_modules/@shopify/checkout-kit-protocol/src/generated/Models.d.ts	53.0 KiB	53.0 KiB	0 B
ios/ShopifyCheckoutKit.swift	13.5 KiB	15.7 KiB	+2.2 KiB
android/src/main/java/com/shopify/reactnative/checkoutkit/ShopifyCheckoutKitModule.java	12.8 KiB	15.2 KiB	+2.5 KiB
ios/AcceleratedCheckoutButtons.swift	14.1 KiB	14.1 KiB	0 B
src/components/AcceleratedCheckoutButtons.tsx	13.0 KiB	13.0 KiB	0 B
src/index.ts	12.2 KiB	12.7 KiB	+466 B
lib/commonjs/index.js	12.3 KiB	12.4 KiB	+149 B
lib/commonjs/components/AcceleratedCheckoutButtons.js	11.4 KiB	11.4 KiB	0 B
src/index.d.ts	9.1 KiB	10.4 KiB	+1.3 KiB
lib/commonjs/components/AcceleratedCheckoutButtons.js.map	10.4 KiB	10.4 KiB	0 B
lib/module/index.js	10.2 KiB	10.4 KiB	+175 B
lib/module/components/AcceleratedCheckoutButtons.js	10.2 KiB	10.2 KiB	0 B
node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolNotifications.ts	9.5 KiB	9.5 KiB	0 B
lib/module/components/AcceleratedCheckoutButtons.js.map	9.1 KiB	9.1 KiB	0 B
lib/module/index.js.map	7.9 KiB	8.1 KiB	+261 B
src/present-dispatcher.ts	8.0 KiB	8.0 KiB	0 B
lib/commonjs/index.js.map	7.7 KiB	7.9 KiB	+260 B
node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolNotifications.d.ts	7.6 KiB	7.6 KiB	0 B
node_modules/@shopify/checkout-kit-protocol/src/generated/ProtocolRenameMap.ts	7.2 KiB	7.2 KiB	0 B
…and 117 smaller files

Measured from the PR base SHA and PR head SHA. The file breakdown shows uncompressed sizes within each package artifact, so individual files do not sum to the compressed artifact total. This comment reports package artifact sizes only; it is not a final app binary-size report.

[bitrise]

Install this build

Open Tophat, select your target device, then click Install. Links open on the Mac running Tophat.

SDK	Install
React Native	Install with Tophat

Checkout Kit E2E results

Status	Suite	Target	Platform	OS version tag	Device
✅	react-native-ios	react-native	ios	latest	iPhone 15 iOS 27 Beta
✅	react-native-android	react-native	android	latest	Google Pixel 9 Android 17.0

[markmur]

• Refresh repeated Swift preloads #658
• Dogfood preload observability in React Native sample #656
• Replace deprecated React Native activity access #655
• Add React Native preload observability #654 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.