Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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

📣  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.


  • Android SDK 21


Add the dependency in your build.gradle:

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

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=""
        <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" />

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:

     import com.braintreepayments.api.PopupBridgeClient;
     class MyWebViewActivity extends Activity {
         private WebView webView;
         private PopupBridgeClient popupBridgeClient;
         protected void onCreate(@Nullable Bundle savedInstanceState) {
             popupBridgeClient = new PopupBridgeClient(this, webView, "my-custom-url-scheme");
             // register error listener
             popupBridgeClient.setErrorListener(error -> showDialog(error.getMessage()));
         protected void onResume() {
             // call 'deliverResult' in onResume to capture a pending result
         protected void onNewIntent(Intent newIntent) {
             // required if your deep link destination activity launch mode is `singleTop`, `singleTask`, or `singleInstance`
  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 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.