[Android] Add advanced present builder callbacks and migrate sample flow

Author: tiagocandido

platforms/android/README.md

@@ -113,10 +113,71 @@ function provided by the SDK:
 ```kotlin
 fun presentCheckout() {
     val checkoutUrl = cart.checkoutUrl
-    ShopifyCheckoutKit.present(checkoutUrl, context, checkoutEventProcessor)
+    ShopifyCheckoutKit.present(checkoutUrl, context) {
+        onComplete { event ->
+            handleCompletedEvent(event)
+        }
+        onFail { error ->
+            handleCheckoutError(error)
+        }
+        onCancel {
+            resetCheckoutUi()
+        }
+    }
 }
 ```
 
+> [!NOTE]
+> Pass the standard `checkoutUrl` returned by Storefront API or a cart permalink.
+> Checkout Kit adds the required UCP query parameters automatically when it loads checkout,
+> so you do not need to rewrite the URL yourself.
+
+If you also want typed Embedded Checkout Protocol (ECP) callbacks, connect a
+`CheckoutProtocol.Client` inside the same Kotlin builder:
+
+```kotlin
+val checkoutProtocolClient = CheckoutProtocol.Client()
+    .on(CheckoutProtocol.start) { checkout ->
+        // Checkout is ready and interactive.
+    }
+    .on(CheckoutProtocol.complete) { checkout ->
+        // Typed checkout payload emitted when checkout completes.
+    }
+    .on(CheckoutProtocol.windowOpen) { request ->
+        startActivity(Intent(Intent.ACTION_VIEW, request.url))
+        WindowOpenResult.Success
+    }
+
+ShopifyCheckoutKit.present(checkoutUrl, activity) {
+    onComplete { event ->
+        handleCompletedEvent(event)
+    }
+    connect(checkoutProtocolClient)
+}
+```
+
+The Kotlin builder also supports optional browser/system callbacks:
+
+```kotlin
+ShopifyCheckoutKit.present(checkoutUrl, activity) {
+    onShowFileChooser { _, filePathCallback, fileChooserParams ->
+        activity.onShowFileChooser(filePathCallback, fileChooserParams)
+    }
+    onGeolocationPermissionsShowPrompt { origin, callback ->
+        activity.onGeolocationPermissionsShowPrompt(origin, callback)
+    }
+    onGeolocationPermissionsHidePrompt {
+        activity.onGeolocationPermissionsHidePrompt()
+    }
+    onPermissionRequest { permissionRequest ->
+        // Optional: grant, deny, or proxy requested web permissions.
+    }
+}
+```
+
+If you prefer a reusable object, or are integrating from Java, `DefaultCheckoutEventProcessor`
+remains available.
+
 > [!TIP]
 > To help optimize and deliver the best experience the SDK also provides a
 > [preloading API](#preloading) that can be used to initialize the checkout session ahead of time.
@@ -317,9 +378,9 @@ The library will automatically invalidate/abort preload under the following cond
 
 - Request results in network error or non 2XX server response code
 - The checkout has successfully completed, as indicated by the server response
-- When `ShopifyCheckoutSheet.configure` is called (e.g. with theming changes).
+- When `ShopifyCheckoutKit.configure` is called (e.g. with theming changes).
 
-A preloaded checkout _is not_ automatically invalidated when checkout is closed. For example, if a buyer loads the checkout then exists, the preloaded checkout is retained and should be updated when cart contents change.
+A preloaded checkout _is not_ automatically invalidated when checkout is closed. For example, if a buyer loads the checkout then exits, the preloaded checkout is retained and should be updated when cart contents change.
 
 #### Additional considerations for preloaded checkout
 
@@ -332,41 +393,57 @@ A preloaded checkout _is not_ automatically invalidated when checkout is closed.
 
 ## Monitoring the lifecycle of a checkout session
 
-Extend the `DefaultCheckoutEventProcessor` abstract class to register callbacks for key lifecycle events during the checkout session:
+For the common lifecycle path, register callbacks directly on `present(...)`:
 
 ```kotlin
-val processor = object : DefaultCheckoutEventProcessor(activity) {
-    override fun onCheckoutCompleted(checkoutCompletedEvent: CheckoutCompletedEvent) {
+ShopifyCheckoutKit.present(checkoutUrl, context) {
+    onComplete { checkoutCompletedEvent ->
         // Called when the checkout was completed successfully by the buyer.
         // Use this to update UI, reset cart state, etc.
     }
 
-    override fun onCheckoutCanceled() {
+    onCancel {
         // Called when the checkout was canceled by the buyer.
         // Note: This will also be received after closing a completed checkout
     }
 
-    override fun onCheckoutFailed(error: CheckoutException) {
+    onFail { error ->
         // Called when the checkout encountered an error and has been aborted.
     }
+}
+```
+
+For browser/system integrations such as file chooser, geolocation, or permission requests,
+you can register handlers directly on the Kotlin builder:
+
+```kotlin
+ShopifyCheckoutKit.present(checkoutUrl, activity) {
+    onShowFileChooser { webView, filePathCallback, fileChooserParams ->
+        // Return true if the host app handled the chooser request.
+        false
+    }
+
+    onGeolocationPermissionsShowPrompt { origin, callback ->
+        // Called to tell the client to show a geolocation permissions prompt as a geolocation
+        // request has been made. Invoked for example if a customer uses `Use my location`
+        // for pickup points.
+    }
+
+    onGeolocationPermissionsHidePrompt {
+        // Called to tell the client to hide the geolocation permissions prompt.
+    }
 
-    override fun onCheckoutLinkClicked(uri: Uri) {
-        // Called when the buyer clicks a link within the checkout experience:
-        // - email address (`mailto:`)
-        // - telephone number (`tel:`)
-        // - web (http:)
-        // - deep link (e.g. myapp://checkout)
-        // and is being directed outside the application.
-
-        // Note: to support deep links on Android 11+ using the `DefaultCheckoutEventProcessor`,
-        // the client app should add a queries element in its manifest declaring which apps it should interact with.
-        // See the MobileBuyIntegration sample's manifest for an example.
-        // Queries reference - https://developer.android.com/guide/topics/manifest/queries-element
-
-        // If no app can be queried to deal with the link, the processor will log a warning:
-        // `Unrecognized scheme for link clicked in checkout` along with the uri.
+    onPermissionRequest { permissionRequest ->
+        // Called when a web permission has been requested, e.g. to access the camera.
     }
+}
+```
+
+If you prefer a reusable object, or are integrating from Java, extend
+`DefaultCheckoutEventProcessor` and pass it to the existing `present(...)` overload:
 
+```kotlin
+val processor = object : DefaultCheckoutEventProcessor() {
     override fun onShowFileChooser(
         webView: WebView,
         filePathCallback: ValueCallback<Array<Uri>>,
@@ -392,10 +469,13 @@ val processor = object : DefaultCheckoutEventProcessor(activity) {
         // implement to grant/deny/request permissions.
     }
 }
+
+ShopifyCheckoutKit.present(checkoutUrl, context, processor)
 ```
 
 > [!Note]
-> The `DefaultCheckoutEventProcessor` provides default implementations for current and future callback functions (such as `onLinkClicked()`), which can be overridden by clients wanting to change default behavior.
+> The `DefaultCheckoutEventProcessor` overload remains available for reusable or Java-facing
+> integrations and provides default implementations for optional browser/system callbacks.
 
 ### Error handling
 
@@ -406,8 +486,8 @@ In the event of a checkout error occurring, the Checkout Kit _may_ attempt to re
 
 There are some caveats to note when this scenario occurs:
 
-1. The checkout experience may look different to buyers. Though the sheet kit will attempt to load any checkoput customizations for the storefront, there is no guarantee they will show in recovery mode.
-2. The `onCheckoutCompleted(checkoutCompletedEvent: CheckoutCompletedEvent)` will be emitted with partial data. Invocations will only received the order ID via `checkoutCompletedEvent.orderDetails.id`.
+1. The checkout experience may look different to buyers. Though the kit will attempt to load any checkout customizations for the storefront, there is no guarantee they will show in recovery mode.
+2. The `onCheckoutCompleted(checkoutCompletedEvent: CheckoutCompletedEvent)` callback will be emitted with partial data. Invocations will only receive the order ID via `checkoutCompletedEvent.orderDetails.id`.
 
 Should you wish to opt-out of this fallback experience entirely, you can do so by overriding `shouldRecoverFromError`. Errors given to the `onCheckoutFailed(error: CheckoutException)` lifecycle method will contain an `isRecoverable` property by default indicating whether the request should be retried or not.
 
@@ -492,7 +572,7 @@ classDiagram
 
 Buyer-aware checkout experience reduces friction and increases conversion. Depending on the context
 of the buyer (guest or signed-in), knowledge of buyer preferences, or account/identity system, the
-application can use on of the following methods to initialize personalized and contextualized buyer
+application can use one of the following methods to initialize personalized and contextualized buyer
 experience.
 
 ### Cart: buyer bag, identity, and preferences

platforms/android/lib/api/lib.api

@@ -756,6 +756,17 @@ public final class com/shopify/checkoutkit/CheckoutLineItem$Companion {
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
 }
 
+public final class com/shopify/checkoutkit/CheckoutPresentation {
+	public final fun connect (Lcom/shopify/checkoutkit/CheckoutCommunicationClient;)V
+	public final fun onCancel (Lkotlin/jvm/functions/Function0;)V
+	public final fun onComplete (Lkotlin/jvm/functions/Function1;)V
+	public final fun onFail (Lkotlin/jvm/functions/Function1;)V
+	public final fun onGeolocationPermissionsHidePrompt (Lkotlin/jvm/functions/Function0;)V
+	public final fun onGeolocationPermissionsShowPrompt (Lkotlin/jvm/functions/Function2;)V
+	public final fun onPermissionRequest (Lkotlin/jvm/functions/Function1;)V
+	public final fun onShowFileChooser (Lkotlin/jvm/functions/Function3;)V
+}
+
 public final class com/shopify/checkoutkit/CheckoutProtocol {
 	public static final field INSTANCE Lcom/shopify/checkoutkit/CheckoutProtocol;
 	public static final field specVersion Ljava/lang/String;
@@ -3927,6 +3938,7 @@ public final class com/shopify/checkoutkit/ShopifyCheckoutKit {
 	public static final fun preload (Ljava/lang/String;Landroidx/activity/ComponentActivity;)V
 	public static final fun present (Ljava/lang/String;Landroidx/activity/ComponentActivity;Lcom/shopify/checkoutkit/DefaultCheckoutEventProcessor;)Lcom/shopify/checkoutkit/CheckoutKitDialog;
 	public static final fun present (Ljava/lang/String;Landroidx/activity/ComponentActivity;Lcom/shopify/checkoutkit/DefaultCheckoutEventProcessor;Lcom/shopify/checkoutkit/CheckoutCommunicationClient;)Lcom/shopify/checkoutkit/CheckoutKitDialog;
+	public static final synthetic fun present (Ljava/lang/String;Landroidx/activity/ComponentActivity;Lkotlin/jvm/functions/Function1;)Lcom/shopify/checkoutkit/CheckoutKitDialog;
 	public static synthetic fun present$default (Ljava/lang/String;Landroidx/activity/ComponentActivity;Lcom/shopify/checkoutkit/DefaultCheckoutEventProcessor;Lcom/shopify/checkoutkit/CheckoutCommunicationClient;ILjava/lang/Object;)Lcom/shopify/checkoutkit/CheckoutKitDialog;
 }
 

platforms/android/lib/src/main/java/com/shopify/checkoutkit/CheckoutPresentation.kt

@@ -0,0 +1,148 @@
+/*
+ * MIT License
+ *
+ * Copyright 2023-present, Shopify Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.shopify.checkoutkit
+
+import android.net.Uri
+import android.webkit.GeolocationPermissions
+import android.webkit.PermissionRequest
+import android.webkit.ValueCallback
+import android.webkit.WebChromeClient
+import android.webkit.WebView
+import com.shopify.checkoutkit.lifecycleevents.CheckoutCompletedEvent
+
+/**
+ * Kotlin-first builder for per-presentation checkout callbacks.
+ *
+ * Use through [ShopifyCheckoutKit.present].
+ */
+public class CheckoutPresentation internal constructor() {
+    internal var onComplete: ((CheckoutCompletedEvent) -> Unit)? = null
+    internal var onFail: ((CheckoutException) -> Unit)? = null
+    internal var onCancel: (() -> Unit)? = null
+    internal var onPermissionRequest: ((PermissionRequest) -> Unit)? = null
+    internal var onShowFileChooser:
+        ((WebView, ValueCallback<Array<Uri>>, WebChromeClient.FileChooserParams) -> Boolean)? = null
+    internal var onGeolocationPermissionsShowPrompt:
+        ((String, GeolocationPermissions.Callback) -> Unit)? = null
+    internal var onGeolocationPermissionsHidePrompt: (() -> Unit)? = null
+    internal var communicationClient: CheckoutCommunicationClient? = null
+
+    /**
+     * Called when checkout completes successfully.
+     */
+    public fun onComplete(handler: (CheckoutCompletedEvent) -> Unit) {
+        onComplete = handler
+    }
+
+    /**
+     * Called when checkout fails.
+     */
+    public fun onFail(handler: (CheckoutException) -> Unit) {
+        onFail = handler
+    }
+
+    /**
+     * Called when checkout is canceled by the buyer.
+     */
+    public fun onCancel(handler: () -> Unit) {
+        onCancel = handler
+    }
+
+    /**
+     * Called when checkout requests a web permission, such as camera access.
+     */
+    public fun onPermissionRequest(handler: (PermissionRequest) -> Unit) {
+        onPermissionRequest = handler
+    }
+
+    /**
+     * Called when checkout requests that the host app present a file chooser.
+     */
+    public fun onShowFileChooser(
+        handler: (
+            webView: WebView,
+            filePathCallback: ValueCallback<Array<Uri>>,
+            fileChooserParams: WebChromeClient.FileChooserParams,
+        ) -> Boolean,
+    ) {
+        onShowFileChooser = handler
+    }
+
+    /**
+     * Called when checkout requests that the host app present a geolocation prompt.
+     */
+    public fun onGeolocationPermissionsShowPrompt(
+        handler: (origin: String, callback: GeolocationPermissions.Callback) -> Unit,
+    ) {
+        onGeolocationPermissionsShowPrompt = handler
+    }
+
+    /**
+     * Called when checkout requests that any visible geolocation prompt be dismissed.
+     */
+    public fun onGeolocationPermissionsHidePrompt(handler: () -> Unit) {
+        onGeolocationPermissionsHidePrompt = handler
+    }
+
+    /**
+     * Connects a communication client for Embedded Checkout Protocol messages.
+     */
+    public fun connect(client: CheckoutCommunicationClient?) {
+        communicationClient = client
+    }
+
+    internal fun buildEventProcessor(): DefaultCheckoutEventProcessor =
+        object : DefaultCheckoutEventProcessor() {
+            override fun onCheckoutCompleted(checkoutCompletedEvent: CheckoutCompletedEvent) {
+                onComplete?.invoke(checkoutCompletedEvent)
+            }
+
+            override fun onCheckoutFailed(error: CheckoutException) {
+                onFail?.invoke(error)
+            }
+
+            override fun onCheckoutCanceled() {
+                onCancel?.invoke()
+            }
+
+            override fun onPermissionRequest(permissionRequest: PermissionRequest) {
+                onPermissionRequest?.invoke(permissionRequest)
+            }
+
+            override fun onShowFileChooser(
+                webView: WebView,
+                filePathCallback: ValueCallback<Array<Uri>>,
+                fileChooserParams: WebChromeClient.FileChooserParams,
+            ): Boolean {
+                return onShowFileChooser?.invoke(webView, filePathCallback, fileChooserParams) ?: false
+            }
+
+            override fun onGeolocationPermissionsShowPrompt(origin: String, callback: GeolocationPermissions.Callback) {
+                onGeolocationPermissionsShowPrompt?.invoke(origin, callback)
+            }
+
+            override fun onGeolocationPermissionsHidePrompt() {
+                onGeolocationPermissionsHidePrompt?.invoke()
+            }
+        }
+}