Activate UCP mode: append ec_version, and ec_color_scheme to checkout URL and update UA

[tiagocandido]

What changes are you making?

Activates Embedded Checkout Protocol (ECP) mode on Android by appending the required query params to the checkout URL before it is loaded into the WebView, and aligns the typed consumer client with Swift PR #65.

Without ec_version in the URL, checkout-web's isLikelyEmbedFromUrl() returns false and ECP mode never initialises — ec.ready, ec.start, and all other protocol messages are never sent to the native side.

URL activation:

• String.appendEcpParams(specVersion, colorScheme): pure extension on UriExtensions.kt, called from CheckoutWebView.loadCheckout() before loadUrl(). Idempotently appends:
  • ec_version — activates ECP mode in checkout-web.
  • ec_color_scheme — light or dark when an explicit scheme is configured; omitted for Automatic and Web.
  • ec_delegate=window.open — delegates link opens to the native bridge via ec.window.open_request.
• BaseWebView.userAgentSuffix(): now uses string interpolation (no more buildString) and produces the same ShopifyCheckoutKit/<version> (Android; Kotlin <kotlin>[ <platform>[/<version>]]) token used as the WebView's User-Agent suffix.
• Platform: changed from enum class to sealed class so each subtype can carry an instance-level version: String?. ReactNative gains an optional version argument (@JvmOverloads preserves Java interop).
• User Agent format updated to "ShopifyCheckoutKit/x (Android; Kotlin y[ <platform>[/<version>]])" — aligns with browser UA conventions.

Typed client alignment with Swift PR #65:

• CheckoutProtocol.specVersion: corrected from unrecognised "2026-01-11" to "2026-04-08" (the version that supports unauthenticated ECP).
• Removed CheckoutProtocol.ready and CheckoutProtocol.paymentChange descriptors — neither is exposed by Swift PR Wire Swift kit for UCP events #65. ec.ready is fully handled inside EmbeddedCheckoutProtocol (ACK-only) and ec.payment.change only fires when payment is delegated, which this SDK does not yet support.
• Added CheckoutProtocol.error descriptor with a typed CheckoutError payload (code, content, severity) decoded from params.messages[0].
• Added custom ExtendsSerializer for the Extends sealed class so it accepts both the string shape ("extends": "dev.ucp.shopping.checkout") and the array shape the spec also allows. Without this, kotlinx.serialization's generated serializer threw on every Checkout payload and no typed handler ever fired.
• Descriptor decoders now log the swallowed exception and raw JSON when decode fails, instead of silently returning null — schema drift surfaces in logcat instead of disappearing.
• Unified ECP log tag (BaseWebView.ECP_LOG_TAG = "CheckoutECP") across the bridge and the typed client; added a payload-decoded log line so consumers can see exactly what their handler is receiving.

How to test

Unit tests (no device required):

cd platforms/android && ./gradlew :lib:test :lib:detekt :lib:lintRelease :lib:apiCheck

Manual (sample app on device/emulator):

1. Build and install the sample app from platforms/android/samples/MobileBuyIntegration.
2. Open checkout.
3. Watch logcat — ECP messages should now appear:

   adb logcat -s CheckoutECP:D

   Before this change: silence. After: Received bridge message: method=ec.ready ... followed by ec.start, ec.totals.change, etc., and a Decoded payload for method=...: Checkout(...) line for each typed handler.

---

Before you merge

Important

• I've 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've updated the relevant platform README (platforms/swift/README.md and/or platforms/android/README.md)

---

Releasing a new Swift version?

• I have bumped the version in platforms/swift/ShopifyCheckoutKit.podspec
• I have bumped the version in platforms/swift/Sources/ShopifyCheckoutKit/ShopifyCheckoutKit.swift
• I have updated platforms/swift/CHANGELOG.md
• I have updated the SwiftPM/CocoaPods version snippets in platforms/swift/README.md (major version only)

Releasing a new Android version?

• I have bumped the versionName in platforms/android/lib/build.gradle
• I have updated platforms/android/CHANGELOG.md
• I have updated the Gradle/Maven version snippets in platforms/android/README.md

Tip

See the Contributing documentation for the full release process per platform.

[tiagocandido]

• Activate UCP mode: append ec_version, and ec_color_scheme to checkout URL and update UA #38 👈 (View in Graphite)
• main

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

[kiftio]

why do we call it entry, sounds like a handler from the name of the collection

[tiagocandido]

Renamed HandlerEntry → Handler and the local entry → handler. Reads much better.