[V3] Encode Pending Browser Switch Request as Base64 String

CHANGELOG.md

@@ -10,9 +10,9 @@
   * Change `BrowserSwitchClient#start` parameters and return type
   * Change `BrowserSwitchClient#parseResult` parameters 
   * Remove `deliverResult`, `getResult`, `captureResult`, `clearActiveRequests`, `getResultFromCache`, and `deliverResultFromCache` from `BrowserSwitchClient`
-  * Add `BrowserSwitchRequest` and `BrowserSwitchPendingRequest`
-  * Convert `BrowserSwitchResult` to sealed class and add `BrowserSwitchResultInfo`
   * Remove `BrowserSwitchStatus`
+  * Add `BrowserSwitchRequest` and `BrowserSwitchStartResult`
+  * Rename `BrowserSwitchResult` to `BrowserSwitchParseResult` and convert it to a sealed class
 
 ## 2.6.1
 

browser-switch/src/main/java/com/braintreepayments/api/BrowserSwitchClient.java

@@ -7,7 +7,6 @@
 
 import androidx.activity.ComponentActivity;
 import androidx.annotation.NonNull;
-import androidx.annotation.Nullable;
 import androidx.annotation.VisibleForTesting;
 
 import com.braintreepayments.api.browserswitch.R;
@@ -41,18 +40,19 @@ public BrowserSwitchClient() {
      * Open a browser or <a href="https://developer.chrome.com/multidevice/android/customtabs">Chrome Custom Tab</a>
      * with a given set of {@link BrowserSwitchOptions} from an Android activity.
      *
-     * @param activity the activity used to start browser switch
+     * @param activity             the activity used to start browser switch
      * @param browserSwitchOptions {@link BrowserSwitchOptions} the options used to configure the browser switch
-     * @return a {@link BrowserSwitchPendingRequest.Started} that should be stored and passed to
-     * {@link BrowserSwitchClient#parseResult(BrowserSwitchPendingRequest.Started, Intent)} upon return to the app,
-     * or {@link BrowserSwitchPendingRequest.Failure} if browser could not be launched.
+     * @return a {@link BrowserSwitchStartResult.Success} that should be stored and passed to
+     * {@link BrowserSwitchClient#parseResult(Intent, String)} upon return to the app,
+     * or {@link BrowserSwitchStartResult.Failure} if browser could not be launched.
      */
     @NonNull
-    public BrowserSwitchPendingRequest start(@NonNull ComponentActivity activity, @NonNull BrowserSwitchOptions browserSwitchOptions) {
+    public BrowserSwitchStartResult start(@NonNull ComponentActivity activity, @NonNull BrowserSwitchOptions browserSwitchOptions) {
+        // TODO: allow browser switching with application context
         try {
             assertCanPerformBrowserSwitch(activity, browserSwitchOptions);
         } catch (BrowserSwitchException e) {
-            return new BrowserSwitchPendingRequest.Failure(e);
+            return new BrowserSwitchStartResult.Failure(e);
         }
 
         Uri browserSwitchUrl = browserSwitchOptions.getUrl();
@@ -64,18 +64,17 @@ public BrowserSwitchPendingRequest start(@NonNull ComponentActivity activity, @N
         if (activity.isFinishing()) {
             String activityFinishingMessage =
                     "Unable to start browser switch while host Activity is finishing.";
-            return new BrowserSwitchPendingRequest.Failure(new BrowserSwitchException(activityFinishingMessage));
-        } else  {
+            return new BrowserSwitchStartResult.Failure(new BrowserSwitchException(activityFinishingMessage));
+        } else {
             boolean launchAsNewTask = browserSwitchOptions.isLaunchAsNewTask();
-            BrowserSwitchRequest request;
             try {
-                 request =
-                        new BrowserSwitchRequest(requestCode, browserSwitchUrl, metadata, returnUrlScheme, true);
+                BrowserSwitchRequest request =
+                        new BrowserSwitchRequest(requestCode, browserSwitchUrl, metadata, returnUrlScheme);
                 customTabsInternalClient.launchUrl(activity, browserSwitchUrl, launchAsNewTask);
-            } catch (ActivityNotFoundException e) {
-                return new BrowserSwitchPendingRequest.Failure(new BrowserSwitchException("Unable to start browser switch without a web browser."));
+                return new BrowserSwitchStartResult.Success(request.toBase64EncodedJSON());
+            } catch (ActivityNotFoundException | BrowserSwitchException e) {
+                return new BrowserSwitchStartResult.Failure(new BrowserSwitchException("Unable to start browser switch without a web browser.", e));
             }
-            return new BrowserSwitchPendingRequest.Started(request);
         }
     }
 
@@ -106,23 +105,30 @@ private boolean isValidRequestCode(int requestCode) {
 
     /**
      * Parses and returns a browser switch result if a match is found for the given {@link BrowserSwitchRequest}
-     * @param pendingRequest the {@link BrowserSwitchPendingRequest.Started} returned from
-     * {@link BrowserSwitchClient#start(ComponentActivity, BrowserSwitchOptions)}
-     * @param intent the intent to return to your application containing a deep link result from the
-     *               browser flow
-     * @return a {@link BrowserSwitchResult.Success} if the browser switch was successfully
-     * completed, or {@link BrowserSwitchResult.NoResult} if no result can be found for the given
-     * {@link BrowserSwitchPendingRequest.Started}. A {@link BrowserSwitchResult.NoResult} will be
+     *
+     * @param intent              the intent to return to your application containing a deep link result from the
+     *                            browser flow
+     * @param pendingRequestState the {@link BrowserSwitchStartResult.Success} token returned from
+     *                            {@link BrowserSwitchClient#start(ComponentActivity, BrowserSwitchOptions)}
+     * @return a {@link BrowserSwitchParseResult.Success} if the browser switch was successfully
+     * completed, or {@link BrowserSwitchParseResult.NoResult} if no result can be found for the given
+     * {@link BrowserSwitchStartResult.Success}. A {@link BrowserSwitchParseResult.NoResult} will be
      * returned if the user returns to the app without completing the browser switch flow.
      */
-    public BrowserSwitchResult parseResult(@NonNull BrowserSwitchPendingRequest.Started pendingRequest, @Nullable Intent intent) {
+    @NonNull
+    public BrowserSwitchParseResult parseResult(@NonNull Intent intent, @NonNull String pendingRequestState) {
         if (intent != null && intent.getData() != null) {
             Uri deepLinkUrl = intent.getData();
-            if (pendingRequest.getBrowserSwitchRequest().matchesDeepLinkUrlScheme(deepLinkUrl)) {
-                BrowserSwitchResultInfo resultInfo = new BrowserSwitchResultInfo(pendingRequest.getBrowserSwitchRequest(), deepLinkUrl);
-                return new BrowserSwitchResult.Success(resultInfo);
+            try {
+                BrowserSwitchRequest pendingRequest =
+                        BrowserSwitchRequest.fromBase64EncodedJSON(pendingRequestState);
+                if (pendingRequest.matchesDeepLinkUrlScheme(deepLinkUrl)) {
+                    return new BrowserSwitchParseResult.Success(deepLinkUrl, pendingRequest);
+                }
+            } catch (BrowserSwitchException e) {
+                return new BrowserSwitchParseResult.Failure(e);
             }
         }
-        return BrowserSwitchResult.NoResult.INSTANCE;
+        return BrowserSwitchParseResult.NoResult.INSTANCE;
     }
 }

browser-switch/src/main/java/com/braintreepayments/api/BrowserSwitchException.java

@@ -8,4 +8,8 @@ public class BrowserSwitchException extends Exception {
     BrowserSwitchException(String message) {
         super(message);
     }
+
+    BrowserSwitchException(String message, Exception reason) {
+        super(message, reason);
+    }
 }

browser-switch/src/main/java/com/braintreepayments/api/BrowserSwitchOptions.java

@@ -9,7 +9,7 @@
 
 /**
  * Object that contains a set of browser switch parameters for use with
- * {@link BrowserSwitchClient#start(FragmentActivity, BrowserSwitchOptions)}.
+ * {@link BrowserSwitchClient#start(androidx.activity.ComponentActivity, BrowserSwitchOptions)}.
  */
 public class BrowserSwitchOptions {
 
@@ -24,7 +24,7 @@ public class BrowserSwitchOptions {
      * Set browser switch metadata.
      *
      * @param metadata JSONObject containing metadata that will be persisted and returned in a
-     *                 {@link BrowserSwitchResultInfo} when the app has re-entered the foreground
+     *                 {@link BrowserSwitchParseResult} when the app has re-entered the foreground
      * @return {@link BrowserSwitchOptions} reference to instance to allow setter invocations to be chained
      */
     public BrowserSwitchOptions metadata(@Nullable JSONObject metadata) {

browser-switch/src/main/java/com/braintreepayments/api/BrowserSwitchParseResult.kt

@@ -0,0 +1,41 @@
+package com.braintreepayments.api
+
+import android.net.Uri
+import org.json.JSONObject
+
+/**
+ * The result of a browser switch obtained from [BrowserSwitchClient.parseResult]
+ */
+sealed class BrowserSwitchParseResult {
+
+    /**
+     * The browser switch was successfully completed. See [resultInfo] for details.
+     */
+    class Success internal constructor(
+        val deepLinkUrl: Uri,
+        val requestCode: Int,
+        val requestUrl: Uri,
+        val requestMetadata: JSONObject?,
+    ) : BrowserSwitchParseResult() {
+        internal constructor(deepLinkUrl: Uri, originalRequest: BrowserSwitchRequest) : this(
+            deepLinkUrl,
+            originalRequest.requestCode,
+            originalRequest.url,
+            originalRequest.metadata
+        )
+    }
+
+    /**
+     * The browser switch failed.
+     * @property [error] Error detailing the reason for the browser switch failure.
+     */
+    class Failure internal constructor(val error: BrowserSwitchException) :
+        BrowserSwitchParseResult()
+
+    /**
+     * No browser switch result was found. This is the expected result when a user cancels the
+     * browser switch flow without completing by closing the browser, or navigates back to the app
+     * without completing the browser switch flow.
+     */
+    object NoResult : BrowserSwitchParseResult()
+}

browser-switch/src/main/java/com/braintreepayments/api/BrowserSwitchRequest.java

@@ -1,39 +1,58 @@
 package com.braintreepayments.api;
 
 import android.net.Uri;
+import android.util.Base64;
 
 import androidx.annotation.NonNull;
 import androidx.annotation.VisibleForTesting;
 
 import org.json.JSONException;
 import org.json.JSONObject;
 
+import java.nio.charset.StandardCharsets;
+
+// Links
+// Base64 Encode a String in Android: https://stackoverflow.com/a/7360440
+
+// TODO: consider encryption
+// Ref: https://medium.com/fw-engineering/sharedpreferences-and-android-keystore-c4eac3373ac7
+
+// TODO: Rename to `BrowserSwitchStartRequest` and remove `BrowserSwitchOptions` in favor this class
 public class BrowserSwitchRequest {
 
+    private static final String KEY_REQUEST_CODE = "requestCode";
+    private static final String KEY_URL = "url";
+    private static final String KEY_RETURN_URL_SCHEME = "returnUrlScheme";
+    private static final String KEY_METADATA = "metadata";
 
     private final Uri url;
     private final int requestCode;
     private final JSONObject metadata;
     @VisibleForTesting
     final String returnUrlScheme;
-    private boolean shouldNotifyCancellation;
-
-    static BrowserSwitchRequest fromJson(String json) throws JSONException {
-        JSONObject jsonObject = new JSONObject(json);
-        int requestCode = jsonObject.getInt("requestCode");
-        String url = jsonObject.getString("url");
-        String returnUrlScheme = jsonObject.getString("returnUrlScheme");
-        JSONObject metadata = jsonObject.optJSONObject("metadata");
-        boolean shouldNotify = jsonObject.optBoolean("shouldNotify", true);
-        return new BrowserSwitchRequest(requestCode, Uri.parse(url), metadata, returnUrlScheme, shouldNotify);
+
+    @NonNull
+    static BrowserSwitchRequest fromBase64EncodedJSON(@NonNull String base64EncodedRequest) throws BrowserSwitchException {
+        byte[] data = Base64.decode(base64EncodedRequest, Base64.DEFAULT);
+        String requestJSONString = new String(data, StandardCharsets.UTF_8);
+        try {
+            JSONObject requestJSON = new JSONObject(requestJSONString);
+            return new BrowserSwitchRequest(
+                    requestJSON.getInt(KEY_REQUEST_CODE),
+                    Uri.parse(requestJSON.getString(KEY_URL)),
+                    requestJSON.optJSONObject(KEY_METADATA),
+                    requestJSON.getString(KEY_RETURN_URL_SCHEME)
+            );
+        } catch (JSONException e) {
+            throw new BrowserSwitchException("Unable to deserialize browser switch state.", e);
+        }
     }
 
-    BrowserSwitchRequest(int requestCode, Uri url, JSONObject metadata, String returnUrlScheme, boolean shouldNotifyCancellation) {
+    BrowserSwitchRequest(int requestCode, Uri url, JSONObject metadata, String returnUrlScheme) {
         this.url = url;
         this.requestCode = requestCode;
         this.metadata = metadata;
         this.returnUrlScheme = returnUrlScheme;
-        this.shouldNotifyCancellation = shouldNotifyCancellation;
     }
 
     Uri getUrl() {
@@ -48,24 +67,20 @@ JSONObject getMetadata() {
         return metadata;
     }
 
-    boolean getShouldNotifyCancellation() {
-        return shouldNotifyCancellation;
-    }
-
-    void setShouldNotifyCancellation(boolean shouldNotifyCancellation) {
-        this.shouldNotifyCancellation = shouldNotifyCancellation;
-    }
+    @NonNull
+    String toBase64EncodedJSON() throws BrowserSwitchException {
+        try {
+            JSONObject requestJSON = new JSONObject()
+                    .put(KEY_REQUEST_CODE, requestCode)
+                    .put(KEY_URL, url.toString())
+                    .put(KEY_RETURN_URL_SCHEME, returnUrlScheme)
+                    .putOpt(KEY_METADATA, metadata);
 
-    String toJson() throws JSONException {
-        JSONObject result = new JSONObject();
-        result.put("requestCode", requestCode);
-        result.put("url", url.toString());
-        result.put("returnUrlScheme", returnUrlScheme);
-        result.put("shouldNotify", shouldNotifyCancellation);
-        if (metadata != null) {
-            result.put("metadata", metadata);
+            byte[] requestJSONBytes = requestJSON.toString().getBytes(StandardCharsets.UTF_8);
+            return Base64.encodeToString(requestJSONBytes, Base64.DEFAULT);
+        } catch (JSONException e) {
+            throw new BrowserSwitchException("Unable to serialize browser switch state.", e);
         }
-        return result.toString();
     }
 
     boolean matchesDeepLinkUrlScheme(@NonNull Uri url) {