Skip to content
PopupBridge allows WebViews to open popup windows in a browser and send data back to the WebView
Java Ruby Shell
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
PopupBridge Prepare for development Feb 5, 2019
PopupBridgeExample Replace with AndroidX version Feb 5, 2019
gradle/wrapper Convert to AndroidX Feb 5, 2019
.gitignore Dont ignore Feb 5, 2019
.travis.yml Update travis build-tools Feb 5, 2019 Add ACKNOWLEDGEMENTS Feb 24, 2017 Release 2.0.0 Feb 5, 2019
LICENSE Update LICENSE year and header Feb 24, 2017 Prepare for development Feb 5, 2019
Rakefile Remove unused part of Rakefile Feb 5, 2019
build.gradle Convert to AndroidX Feb 5, 2019 Fix version check when deploying a snapshot on travis Aug 10, 2017 Replace with AndroidX version Feb 5, 2019
gradlew Initial commit Feb 23, 2017
gradlew.bat Initial commit Feb 23, 2017
popup-bridge-android.gif Add animated gif Mar 2, 2017 Add PayPal instructions to README (#8) Jul 5, 2017
settings.gradle Initial commit Feb 23, 2017


Build Status

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.

PopupBridge Demo gif

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.


  • Android SDK 19


Add the dependency in your build.gradle:

dependencies {
  implementation 'com.braintreepayments:popup-bridge:2.0.0'

To use the latest build from the master branch use:

dependencies {
  implementation 'com.braintreepayments:popup-bridge:2.0.1-SNAPSHOT'

Quick Start

  1. Add PopupBridgeActivity to AndroidManifest.xml and register a custom URL scheme:
<activity android:name="com.braintreepayments.popupbridge.PopupBridgeActivity"
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="${applicationId}.popupbridge" />
  1. Include PopupBridge in your app code:

    import com.braintreepayments.popupbridge.PopupBridge;
    class MyWebViewActivity extends Activity {
        private WebView mWebView;
        public void onCreate() {
            // Connect your web view.
            // ...
            // ...and then attach PopupBridge.
            PopupBridge.newInstance(this, mWebView);
  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 + '?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.addEventListener('message', function (event) {
        var color = JSON.parse(;
        if (color) {
          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>
    $('a').on('click', function (event) {
      var color = $(this).data('color');
      if ('popupBridgeReturnUrlPrefix') !== -1) {
        var prefix ='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 }), '*');

Frequently Asked Questions

Why use PopupBridge?

By default, WebViews cannot open popups -- 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 to open the popup URL
    • 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 in the format of ${applicationId}.popupbridge, which 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: + '?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 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.


  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 ''
      2. Implement a method in your native app for sending device data. See the Android code snippet for PayPal + PopupBridge
  5. Profit!




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

You can’t perform that action at this time.