Activate ECP mode: append ec_version, source, and ec_color_scheme to checkout URL

[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:

• CheckoutWebView.buildEcpUrl(): new private helper, called from loadCheckout() before loadUrl(), that idempotently appends:
  • ec_version — activates ECP mode in checkout-web.
  • source — same ShopifyCheckoutKit/<version> (Android;<os>[;<platform>;<version>]) token used in the User Agent, providing a redundant signal for iframes that can't read the UA header.
  • ec_color_scheme — light or dark when an explicit scheme is configured; omitted for Automatic and Web.
• BaseWebView.buildSourceToken(): extracted from userAgentSuffix() so the same token is shared by both the User Agent and the source param.
• 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; <os>[; <platform>; <version>])" — aligns with browser UA conventions and matches the source param format.

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 that checkout-web actually sends. 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) across the bridge and the typed client; added a payload-decoded log line so consumers can see exactly what their handler is receiving.
• Split log tags: JS console messages go to CheckoutWebViewJS; CheckoutECP is reserved for ECP bridge traffic so consumers can filter the protocol stream cleanly (adb logcat -s CheckoutECP:D).

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: ← RECV: 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 ECP mode: append ec_version, source, and ec_color_scheme to checkout URL #38 👈 (View in Graphite)
• main

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

[markmur]

Just missing messages.change here