PopupBridge

PopupBridge is an Android library that allows WebViews to open popup windows in a browser and send data back to the parent page in the WebView.

📣  A new major version of the SDK is available in beta. See the v4 migration guide for details.

PopupBridge is also available for iOS.

See the Frequently Asked Questions to learn more about PopupBridge. See Using PayPal in a WebView to use PopupBridge with PayPal.

Requirements

• Android SDK 21

Installation

Add the dependency in your build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:popup-bridge:4.1.0'
}

To preview the latest work in progress builds, add the following SNAPSHOT dependency in your build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:popup-bridge:4.1.1-SNAPSHOT'
}

You will also need to add the Sonatype snapshots repo to your top-level build.gradle to import SNAPSHOT builds:

allprojects {
    repositories {
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots/'
        }
    }
}

Quick Start

1. In the AndroidManifest.xml, add an intent-filter to your deep link destination Activity and register a custom URL scheme:

<activity android:name="com.company.app.MyPopupBridgeActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="my-custom-url-scheme" />
    </intent-filter>
</activity>

Note: android:exported is required if your app compile SDK version is API 31 (Android 12) or later. Note: The scheme you define must use all lowercase letters.

1. Instantiate a PopupBridgeClient in your app:

    package com.company.myapp;
   
    import com.braintreepayments.api.PopupBridgeClient;
   
    class MyWebViewActivity extends Activity {
   
        private WebView webView;
        private PopupBridgeClient popupBridgeClient;
   
        @Override
        protected void onCreate(@Nullable Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            popupBridgeClient = new PopupBridgeClient(this, webView, "my-custom-url-scheme");
          
            // register error listener
            popupBridgeClient.setErrorListener(error -> showDialog(error.getMessage()));
   
            webView.loadUrl("https://www.example.com/my_web_app");
        }
   
        @Override
        protected void onNewIntent(Intent newIntent) {
            // required if your deep link destination activity launch mode is `singleTop`, `singleTask`, or `singleInstance`
            super.onNewIntent(newIntent);
            setIntent(newIntent);
        }
    }

2. Use PopupBridge from the web page by writing some JavaScript:

   var url = 'http://localhost:4567/'; // the url you wish to open in a popup
   
   if (window.popupBridge) {
     // Open the popup in a browser, and give it the deep link back to the app
     popupBridge.open(url + '?popupBridgeReturnUrlPrefix=' + popupBridge.getReturnUrlPrefix());
   
     // Optional: define a callback to process results of interaction with the popup
     popupBridge.onComplete = function (err, payload) {
       if (err) {
         console.error('PopupBridge onComplete Error:', err);
       } else if (!err && !payload) {
         console.log('User closed popup.');
       } else {
         alert('Your favorite color is ' + payload.queryItems.color);
   
         console.log(payload.path) // defaults to ""
         console.log(payload.hash) // defaults to ""
       }
     };
   } else {
     var popup = window.open(url);
   
     window.addEventListener('message', function (event) {
       var color = JSON.parse(event.data).color;
   
       if (color) {
         popup.close();
         alert('Your favorite color is ' + color);
       }
     });
   }

3. Redirect back to the app inside of the popup:

   <h1>What is your favorite color?</h1>
   
   <a href="#" data-color="red">Red</a>
   <a href="#" data-color="green">Green</a>
   <a href="#" data-color="blue">Blue</a>
   
   <script src="jquery.js"></script>
   <script>
   $('a').on('click', function (event) {
     var color = $(this).data('color');
   
     if (location.search.indexOf('popupBridgeReturnUrlPrefix') !== -1) {
       var prefix = location.search.split('popupBridgeReturnUrlPrefix=')[1];
       // Open the deep link back to the app, and send some data
       location.href = prefix + '?color=' + color;
     } else {
       window.opener.postMessage(JSON.stringify({ color: color }), '*');
     }
   });
   </script>

Frequently Asked Questions

Why use PopupBridge?

By default, WebViews cannot open popups -- window.open will not work.

You can use setSupportMultipleWindows() and roll your own WebChromeClient and manage the windows yourself, but this does not allow popups to communicate back to the parent WebView.

What are some use cases for using PopupBridge?

• Apps with WebViews that need to open a popup
• When a popup window needs to send data from the popup back to the WebView
• When the popup window needs to display the HTTPS lock icon to increase user trust
• Apps that use OAuth

How does it work?

• PopupBridge attaches to a WebView through the Android JavaScript interface
  • This exposes a JavaScript interface (via window.popupBridge) for the web page to interact with the Android app code
• The web page detects whether the page has access to window.popupBridge; if so, it uses popupBridge.open to open the popup URL
  • popupBridge.open creates an Intent to open the popup URL, which Android forwards to the user's selected browser
  • The web page can also use popupBridge.onComplete as a callback
• The popup web page uses a deep link URL to return back to the app

  • The deep link is registered as a custom URL scheme in AndroidManifest.xml

  • One way to avoid hard-coding the deep link is by adding it as a query parameter to the popup URL:

      popupBridge.open(url + '?popupBridgeReturnUrlPrefix=' + popupBridge.getReturnUrlPrefix());

    • Optionally, you can add path components, query parameters, hash values to the deep link URL to return data to the parent page, which are provided in the payload of popupBridge.onComplete
• If the user hits the back button or manually navigates back to the app, popupBridge.onComplete gets called with the error and payload as null

Who built PopupBridge?

We are a team of engineers who work on the Developer Experience team at Braintree.

Why did Braintree build PopupBridge?

Short answer: to accept PayPal as a payment option when mobile apps are using a WebView to power the checkout process.

PayPal used to support authentication via a modal iframe, but authentication now occurs in a popup window to increase user confidence that their account information is protected from malicious actors (the address bar shows paypal.com with the HTTPS lock icon). However, this causes issues with Braintree merchants who use a web page to power payments within their apps: they cannot accept PayPal because WebViews cannot open popups and return the PayPal payment authorization data to the parent checkout page.

PopupBridge solves this problem by allowing braintree-web or PayPal's Checkout.js to open the PayPal popup from a secure mini-browser.

Using PayPal in a WebView

WebView-based checkout flows can accept PayPal with PopupBridge and the Braintree JS SDK or PayPal's Checkout.js. For the authentication flow, PayPal requires a popup window—which can be simulated with PopupBridge.

Setup

1. Create a web-based checkout that accepts PayPal using Checkout.js or the Braintree JS SDK
2. Create a native mobile app that opens the checkout in a WebView (see steps 1-2 in quick start)
3. Integrate the PopupBridge library
4. Collect device data
   • To help detect fraudulent activity, collect device data before performing PayPal transactions. This is similar to collecting device data with our native Android SDK:
     1. Include PayPalDataCollector in your build.gradle dependencies, e.g. compile 'com.paypal.android.sdk:data-collector:2.+'
     2. Implement a method in your native app for sending device data. See the Android code snippet for PayPal + PopupBridge
5. Profit!

Author

Braintree, [email protected]

License

PopupBridge is available under the MIT license. See the LICENSE file for more info.