[Android] Add preload state observability

[markmur]

Adds observable lifecycle state to preloaded checkouts on Android, mirroring the iOS CheckoutPreload API. preload(checkoutUrl, context, onStateChange) now returns a retained CheckoutPreload handle exposing a state property and an onStateChange callback that emit Loading → Ready → Expired, plus Failed(reason) for HTTP and navigation failures, and Idle on manual invalidation. State is driven from a single transition choke point in the preload cache and broadcast to a weak observer, so consumers can drive spinners or fall back to a fresh preload when a warm entry lapses.

Android has no keep-alive timer, so there is no keepAliveLost reason and expiry is evaluated lazily when a cached entry is taken.

// Retain the handle for as long as you want to observe.
val preload = ShopifyCheckoutKit.preload(checkoutUrl, activity) { state ->
    when (state) {
        PreloadState.Loading -> showSpinner()
        PreloadState.Ready -> hideSpinner()
        PreloadState.Expired -> preloadCheckoutIfNeeded() // warm entry is gone — kick off a fresh preload
        is PreloadState.Failed -> log("preload failed: ${state.reason}")
        PreloadState.Idle -> Unit
    }
}

// Pull the current state at any time.
if (preload.state == PreloadState.Ready) {
    present(checkoutUrl, activity)
}

[markmur]

• [Android] Add preload state observability #451 : 2 dependent PRs (#447 , #455 ) 👈 (View in Graphite)
• main

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

[github-actions]

React Native — Coverage Report

Lines	Statements	Branches	Functions
	91.85% (327/356)	87.98% (183/208)	100% (86/86)

[github-actions]

Package Size

Platform	Artifact	Base	Head	Delta
Android	release AAR	246.4 KiB	257.7 KiB	+11.3 KiB

Android file breakdown

File	Base	Head	Delta
classes.jar	260.6 KiB	273.6 KiB	+13.0 KiB
res/layout/checkout_view_content.xml	2.2 KiB	2.2 KiB	0 B
res/layout/checkout_sheet_content.xml	2.0 KiB	2.0 KiB	0 B
res/values/values.xml	1.2 KiB	1.2 KiB	0 B
R.txt	1.1 KiB	1.1 KiB	0 B
proguard.txt	798 B	798 B	0 B
AndroidManifest.xml	578 B	578 B	0 B
res/drawable/close.xml	431 B	431 B	0 B
res/menu/checkout_menu.xml	354 B	354 B	0 B
META-INF/com/android/build/gradle/aar-metadata.properties	157 B	157 B	0 B

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.

[kiftio]

[Re: line +69]

Do we also need a transition here? E.g. a state of PreloadState.consumed or similar

Or from another angle, do we need to actually consume preloads in this way :hmm:

See this comment inline on Graphite.

[markmur]

I'm just leaving it as .ready across platforms for now. I didn't introduce any state to indicate that it's been presented, but it's worth considering.

Something like this might work:

.idle → .loading → .ready → .presented → (dismiss) .ready → .expired

[bitrise]

Install this build

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

SDK	Install
Kotlin	Install with Tophat

Checkout Kit E2E results

Status	Suite	Target	Platform	OS version tag	Device
✅	tests/shared/launch-smoke.yaml	kotlin	android	latest	Google Pixel 9 Android 17.0

[kiftio]

On iOS, assigning onStateChange immediately replays the current state via a didSet; on Android listener is a plain property with no replay, so a consumer who attaches a listener after obtaining the handle receives nothing until the next transition.

I think this gets us closer to iOS / didSet

public var listener: PreloadStateListener? = null
        set(value) {
            field = value
            value?.onStateChanged(cache.state)
        }

[markmur]

Updated. Assigning listener now immediately replays the current state on the main thread, matching iOS.

[kiftio]

The cache stores the observer as a WeakReference<CheckoutPreload>, and preload(url, activity) { state -> ...} returns the handle but nothing else retains it.

Only Loading fires synchronously, al the later states are driven by async WebView callbacks.

Because the old API returned Unit, folks migrating might keep that call shape, and add the trailing lambda (i.e. no assigning handle to a variable). That would mean CheckoutPreload is unreferenced and eligible for garbage collection right after the preload call returns.

If it gets collected, consumers might not get the other state transitions.

I wonder if we should keep a handle to CheckoutPreload in the library (until a terminal state / another preload call / preload consumed / preload fails)? Maybe passing the listener into CheckoutWebView.preload(), passing into preloadCache.store() storing as an instance var in the cache, and then setting to null at various transitions

[markmur]

Agreed. The cache now strongly retains the current CheckoutPreload, so callback-only usage continues receiving asynchronous transitions. It releases the observer on Idle, Expired, or Failed, or replaces it when another preload starts. Cleanup is reentrancy-safe, so callbacks can start a replacement preload.