Fix Venmo App Switch (#99)

* feat: add returnURLScheme init for Venmo app switch

Add `init(webView:returnURLScheme:prefersEphemeralWebBrowserSession:)`, funneled
through a single internal designated init that also injects a `URLOpener` for
testing. When a returnURLScheme is provided and the Venmo app is installed,
configureWebView advertises that scheme to the JS layer as the return URL prefix
(getReturnUrlPrefix); otherwise it keeps the internal ASWeb callback scheme.

Adds MockURLOpener + tests for the scheme branching, demo Info.plist URL scheme
registration, and README/CHANGELOG updates.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix: use one effective return scheme across ASWeb and app switch

The web SDK reads getReturnUrlPrefix() for both the ASWeb popup and the Venmo
app switch, so the return scheme must be consistent everywhere. Previously only
getReturnUrlPrefix() switched to the merchant scheme (for Venmo) while the ASWeb
callbackURLScheme and the return-URL validation stayed hardcoded to the SDK
scheme, which broke the ASWeb popup return (endless spinner).

Compute the effective scheme once (merchant scheme when a returnURLScheme is
provided and the Venmo app is installed, otherwise the SDK callback scheme) and
use it for the user script prefix, the ASWebAuthenticationSession
callbackURLScheme, and constructJavaScriptCompletionResult validation. Adds a
configurable callbackURLScheme on WebAuthenticationSession and validation tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: refine returnURLScheme README/CHANGELOG wording

Also re-sync Podfile.lock checksum with main's merged Podfile.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Update Sources/PopupBridge/POPPopupBridge.swift

Co-authored-by: agedd <105314544+agedd@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Jax DesMarais-Leder <jdesmarais@paypal.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: agedd <105314544+agedd@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -1,5 +1,8 @@
 # PopupBridge iOS Release Notes
 
+## unreleased
+* Add `init(webView:returnURLScheme:prefersEphemeralWebBrowserSession:)` for the Venmo app switch flow. When a `returnURLScheme` is provided and the Venmo app is installed, PopupBridge sends that scheme to the web SDK as the return URL prefix (`window.popupBridge.getReturnUrlPrefix()`) so the Venmo app can deep-link back into your app.
+
 ## 3.0.0 (2025-04-01)
 * Breaking Changes
   * Bump minimum supported deployment target to iOS 16+

Demo/Demo/Info.plist

@@ -18,6 +18,19 @@
 	<string>3.0.0</string>
 	<key>CFBundleVersion</key>
 	<string>3.0.0</string>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleTypeRole</key>
+			<string>Editor</string>
+			<key>CFBundleURLName</key>
+			<string>com.braintreepayments.Demo</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>com.braintreepayments.Demo</string>
+			</array>
+		</dict>
+	</array>
 	<key>LSApplicationQueriesSchemes</key>
 	<array>
 		<string>com.venmo.touch.v2</string>

Demo/Demo/PopupBridgeViewController.swift

@@ -15,7 +15,7 @@ final class PopupBridgeViewController: UIViewController {
     override func viewDidLoad() {
         super.viewDidLoad()
         setupConstraints()
-        popupBridge = POPPopupBridge(webView: webView)
+        popupBridge = POPPopupBridge(webView: webView, returnURLScheme: "com.braintreepayments.Demo")
         webView.load(URLRequest(url: URL(string: "https://braintree.github.io/popup-bridge-example/")!))
     }
 

Podfile.lock

@@ -11,6 +11,6 @@ SPEC REPOS:
 SPEC CHECKSUMS:
   xcbeautify: df17aa32d769add7af523a8be9b0ef8fb9eb75a8
 
-PODFILE CHECKSUM: f7e2246cbe0f5ad54fc1270994bd0f76a5ed948d
+PODFILE CHECKSUM: f41bb7beb906268c485bb81d6560025898b05cb3
 
 COCOAPODS: 1.16.2

PopupBridge.xcodeproj/project.pbxproj

@@ -13,6 +13,7 @@
 		451348272D8CAD7C009265C9 /* WebViewScriptHandler.swift in Sources */ = {isa = PBXBuildFile; fileRef = 451348262D8CAD6D009265C9 /* WebViewScriptHandler.swift */; };
 		4513482B2D8DDA25009265C9 /* XCTestCase+trackForMemoryLeaks.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4513482A2D8DDA17009265C9 /* XCTestCase+trackForMemoryLeaks.swift */; };
 		45AE41D22D7649F800388548 /* MockAnalyticsService.swift in Sources */ = {isa = PBXBuildFile; fileRef = 45AE41D12D7649EE00388548 /* MockAnalyticsService.swift */; };
+		B7C9D0E12F00000000000002 /* MockURLOpener.swift in Sources */ = {isa = PBXBuildFile; fileRef = B7C9D0E12F00000000000001 /* MockURLOpener.swift */; };
 		45CD0C2C2D64F08F0072C5A4 /* FPTIBatchData.swift in Sources */ = {isa = PBXBuildFile; fileRef = 45CD0C2B2D64F0810072C5A4 /* FPTIBatchData.swift */; };
 		45CD0C2E2D664D140072C5A4 /* Date+MilisecondTimestamp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 45CD0C2D2D664CF50072C5A4 /* Date+MilisecondTimestamp.swift */; };
 		45CD0C302D6788A10072C5A4 /* Bundle+Extension.swift in Sources */ = {isa = PBXBuildFile; fileRef = 45CD0C2F2D67888F0072C5A4 /* Bundle+Extension.swift */; };
@@ -54,6 +55,7 @@
 		451348262D8CAD6D009265C9 /* WebViewScriptHandler.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WebViewScriptHandler.swift; sourceTree = "<group>"; };
 		4513482A2D8DDA17009265C9 /* XCTestCase+trackForMemoryLeaks.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "XCTestCase+trackForMemoryLeaks.swift"; sourceTree = "<group>"; };
 		45AE41D12D7649EE00388548 /* MockAnalyticsService.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MockAnalyticsService.swift; sourceTree = "<group>"; };
+		B7C9D0E12F00000000000001 /* MockURLOpener.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MockURLOpener.swift; sourceTree = "<group>"; };
 		45CD0C2B2D64F0810072C5A4 /* FPTIBatchData.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FPTIBatchData.swift; sourceTree = "<group>"; };
 		45CD0C2D2D664CF50072C5A4 /* Date+MilisecondTimestamp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Date+MilisecondTimestamp.swift"; sourceTree = "<group>"; };
 		45CD0C2F2D67888F0072C5A4 /* Bundle+Extension.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Bundle+Extension.swift"; sourceTree = "<group>"; };
@@ -223,6 +225,7 @@
 				45FBAF342D70CFB6000D550B /* AnalyticsService_Test.swift */,
 				A775A0801DEE4E7E009E67C2 /* Info.plist */,
 				45AE41D12D7649EE00388548 /* MockAnalyticsService.swift */,
+				B7C9D0E12F00000000000001 /* MockURLOpener.swift */,
 				BE2524552A17FB9F00168D77 /* MockScriptMessage.swift */,
 				45FBAF2E2D701E1D000D550B /* MockSessionable.swift */,
 				BE2524532A17DFCC00168D77 /* MockUserContentController.swift */,
@@ -472,6 +475,7 @@
 				BE2524542A17DFCC00168D77 /* MockUserContentController.swift in Sources */,
 				4513482B2D8DDA25009265C9 /* XCTestCase+trackForMemoryLeaks.swift in Sources */,
 				45AE41D22D7649F800388548 /* MockAnalyticsService.swift in Sources */,
+				B7C9D0E12F00000000000002 /* MockURLOpener.swift in Sources */,
 				BE2524562A17FB9F00168D77 /* MockScriptMessage.swift in Sources */,
 				BEF9ED212A2A4896005D54AB /* MockWebAuthenticationSession.swift in Sources */,
 				BE2524522A17DF8200168D77 /* PopupBridge_UnitTests.swift in Sources */,

README.md

@@ -47,6 +47,30 @@ You must add the following to the queries schemes allowlist in your app's info.p
 </array>
 ```
 
+### Register your return URL scheme (Venmo app switch)
+
+When using the Venmo app switch flow, initialize PopupBridge with the URL scheme your app is registered to handle:
+
+```swift
+popupBridge = POPPopupBridge(webView: webView, returnURLScheme: "your-app-scheme")
+```
+
+When the Venmo app is installed, PopupBridge sends this scheme to the web SDK as the return URL prefix (`window.popupBridge.getReturnUrlPrefix()`), so the Venmo app can deep-link back into your app. You must register the same scheme under `CFBundleURLTypes` in your app's `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>your-app-scheme</string>
+    </array>
+  </dict>
+</array>
+```
+
+Additionally, you must add this scheme to your applications URL types. All 3 cases must match exactly to return to your app as expected after completing the app switch flow.
+
 Sample App
 -------
 

Sources/PopupBridge/POPPopupBridge.swift

@@ -16,27 +16,91 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
     private let hostName = "popupbridgev1"
     private let sessionID = UUID().uuidString.replacingOccurrences(of: "-", with: "")
     private let webView: WKWebView
-    private let application: URLOpener = UIApplication.shared
+    private let returnURLScheme: String?
+    private var application: URLOpener = UIApplication.shared
 
     private var webAuthenticationSession: WebAuthenticationSession = WebAuthenticationSession()
     private var returnBlock: ((URL) -> Void)? = nil
-    
+
+    /// The URL scheme used consistently across the return URL prefix advertised to the JS
+    /// (`getReturnUrlPrefix()`), the ASWeb `callbackURLScheme`, and the return-URL validation. When a
+    /// `returnURLScheme` is provided and the Venmo app is installed, the flow app switches into the
+    /// Venmo app (which returns via the merchant scheme), so the merchant scheme is used everywhere.
+    /// Otherwise the SDK's internal callback scheme is used (the standard ASWeb popup flow). The web
+    /// SDK reads `getReturnUrlPrefix()` for both flows, so all three must agree on this one scheme.
+    private var returnURLPrefixScheme: String {
+        if let returnURLScheme, application.isVenmoAppInstalled() {
+            return returnURLScheme
+        }
+        return PopupBridgeConstants.callbackURLScheme
+    }
+
     // MARK: - Initializers
 
-    /// Initialize a Popup Bridge.
+    /// Initialize a Popup Bridge for the standard browser-based (ASWeb) checkout flow.
     /// - Parameters:
     ///   - webView: The web view to add a script message handler to. Do not change the web view's configuration or user content controller after initializing Popup Bridge.
     ///   - prefersEphemeralWebBrowserSession: A Boolean that, when true, requests that the browser does not share cookies
-    ///   or other browsing data between the authenthication session and the user’s normal browser session.
+    ///   or other browsing data between the authentication session and the user's normal browser session.
     ///   Defaults to `true`.
-    public init(webView: WKWebView, prefersEphemeralWebBrowserSession: Bool = true) {
+    public convenience init(webView: WKWebView, prefersEphemeralWebBrowserSession: Bool = true) {
+        self.init(
+            webView: webView,
+            webAuthenticationSession: WebAuthenticationSession(),
+            returnURLScheme: nil,
+            application: UIApplication.shared,
+            prefersEphemeralWebBrowserSession: prefersEphemeralWebBrowserSession
+        )
+    }
+
+    /// Initialize a Popup Bridge with a return URL scheme for app switch flows (e.g. Venmo).
+    ///
+    /// When a `returnURLScheme` is provided and the Venmo app is installed, the flow app switches into
+    /// the Venmo app, which deep-links back into the app via this scheme. In that case the scheme is
+    /// advertised to the JavaScript layer as the return URL prefix (instead of the SDK's internal
+    /// ASWeb callback scheme).
+    /// - Parameters:
+    ///   - webView: The web view to add a script message handler to. Do not change the web view's configuration or user content controller after initializing Popup Bridge.
+    ///   - returnURLScheme: The URL scheme registered under `CFBundleURLTypes` in the app's `Info.plist`
+    ///   that the Venmo app uses to deep-link back into the app.
+    ///   - prefersEphemeralWebBrowserSession: A Boolean that, when true, requests that the browser does not share cookies
+    ///   or other browsing data between the authentication session and the user's normal browser session.
+    ///   Defaults to `true`.
+    public convenience init(webView: WKWebView, returnURLScheme: String, prefersEphemeralWebBrowserSession: Bool = true) {
+        self.init(
+            webView: webView,
+            webAuthenticationSession: WebAuthenticationSession(),
+            returnURLScheme: returnURLScheme,
+            application: UIApplication.shared,
+            prefersEphemeralWebBrowserSession: prefersEphemeralWebBrowserSession
+        )
+    }
+
+    /// Exposed for testing.
+    ///
+    /// Designated initializer that injects a custom `WebAuthenticationSession` and `URLOpener` so tests
+    /// can stub the browser authentication flow and simulate whether the Venmo app is installed. Kept
+    /// `internal` so the only public entry points are the two initializers above, keeping the internal
+    /// `URLOpener` out of the public API. `returnURLScheme` must be set before `configureWebView()`
+    /// runs so the generated user script advertises the correct return URL prefix.
+    init(
+        webView: WKWebView,
+        webAuthenticationSession: WebAuthenticationSession,
+        returnURLScheme: String? = nil,
+        application: URLOpener = UIApplication.shared,
+        prefersEphemeralWebBrowserSession: Bool = true
+    ) {
         self.webView = webView
-        
+        self.webAuthenticationSession = webAuthenticationSession
+        self.returnURLScheme = returnURLScheme
+        self.application = application
+
         super.init()
 
         configureWebView()
-        webAuthenticationSession.prefersEphemeralWebBrowserSession = prefersEphemeralWebBrowserSession
-                
+        self.webAuthenticationSession.prefersEphemeralWebBrowserSession = prefersEphemeralWebBrowserSession
+        self.webAuthenticationSession.callbackURLScheme = returnURLPrefixScheme
+
         returnBlock = { [weak self] url in
             guard let script = self?.constructJavaScriptCompletionResult(returnURL: url) else {
                 return
@@ -46,15 +110,6 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
             return
         }
     }
-
-    /// Exposed for testing
-    convenience init(
-        webView: WKWebView,
-        webAuthenticationSession: WebAuthenticationSession
-    ) {
-        self.init(webView: webView)
-        self.webAuthenticationSession = webAuthenticationSession
-    }
 
     deinit {
         webView.configuration.userContentController.removeAllScriptMessageHandlers()
@@ -69,7 +124,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
     /// - Returns: JavaScript formatted completion.
     func constructJavaScriptCompletionResult(returnURL: URL) -> String? {
         guard let urlComponents = URLComponents(url: returnURL, resolvingAgainstBaseURL: false),
-              urlComponents.scheme?.caseInsensitiveCompare(PopupBridgeConstants.callbackURLScheme) == .orderedSame,
+              urlComponents.scheme?.caseInsensitiveCompare(returnURLPrefixScheme) == .orderedSame,
               urlComponents.host?.caseInsensitiveCompare(hostName) == .orderedSame
         else {
             return nil
@@ -107,7 +162,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
         )
 
         let javascript = PopupBridgeUserScript(
-            scheme: PopupBridgeConstants.callbackURLScheme,
+            scheme: returnURLPrefixScheme,
             scriptMessageHandlerName: messageHandlerName,
             host: hostName,
             isVenmoInstalled: application.isVenmoAppInstalled()

Sources/PopupBridge/WebAuthenticationSession.swift

@@ -5,6 +5,7 @@ class WebAuthenticationSession: NSObject {
 
     var authenticationSession: ASWebAuthenticationSession?
     var prefersEphemeralWebBrowserSession: Bool = true
+    var callbackURLScheme: String = PopupBridgeConstants.callbackURLScheme
 
     func start(
         url: URL,
@@ -14,7 +15,7 @@ class WebAuthenticationSession: NSObject {
     ) {
         self.authenticationSession = ASWebAuthenticationSession(
             url: url,
-            callbackURLScheme: PopupBridgeConstants.callbackURLScheme
+            callbackURLScheme: callbackURLScheme
         ) { url, error in
             if let error = error as? NSError, error.code == ASWebAuthenticationSessionError.canceledLogin.rawValue {
                 sessionDidCancel()

UnitTests/MockURLOpener.swift

@@ -0,0 +1,11 @@
+import Foundation
+@testable import PopupBridge
+
+class MockURLOpener: URLOpener {
+
+    var venmoInstalled = false
+
+    func isVenmoAppInstalled() -> Bool {
+        venmoInstalled
+    }
+}

UnitTests/PopupBridge_UnitTests.swift

@@ -373,4 +373,92 @@ final class PopupBridge_UnitTests: XCTestCase, WKNavigationDelegate {
         ))
         webView.load(URLRequest(url: URL(string: "some-popup-bridge-example")!))
     }
+
+    // MARK: - returnURLScheme app switch tests
+
+    func testUserScript_whenReturnURLSchemeProvidedAndVenmoInstalled_advertisesReturnURLSchemeAsReturnUrlPrefix() {
+        let mockURLOpener = MockURLOpener()
+        mockURLOpener.venmoInstalled = true
+
+        let webView = WKWebView()
+        _ = POPPopupBridge(
+            webView: webView,
+            webAuthenticationSession: mockWebAuthenticationSession,
+            returnURLScheme: "my-app-scheme",
+            application: mockURLOpener
+        )
+
+        let userScript = webView.configuration.userContentController.userScripts[0]
+        XCTAssertTrue(userScript.source.contains("return 'my-app-scheme://popupbridgev1/';"))
+    }
+
+    func testUserScript_whenReturnURLSchemeProvidedButVenmoNotInstalled_advertisesCallbackScheme() {
+        let mockURLOpener = MockURLOpener()
+        mockURLOpener.venmoInstalled = false
+
+        let webView = WKWebView()
+        _ = POPPopupBridge(
+            webView: webView,
+            webAuthenticationSession: mockWebAuthenticationSession,
+            returnURLScheme: "my-app-scheme",
+            application: mockURLOpener
+        )
+
+        let userScript = webView.configuration.userContentController.userScripts[0]
+        XCTAssertTrue(userScript.source.contains("return 'sdk.ios.popup-bridge://popupbridgev1/';"))
+    }
+
+    func testUserScript_whenNoReturnURLSchemeAndVenmoInstalled_advertisesCallbackScheme() {
+        let mockURLOpener = MockURLOpener()
+        mockURLOpener.venmoInstalled = true
+
+        let webView = WKWebView()
+        _ = POPPopupBridge(
+            webView: webView,
+            webAuthenticationSession: mockWebAuthenticationSession,
+            application: mockURLOpener
+        )
+
+        let userScript = webView.configuration.userContentController.userScripts[0]
+        XCTAssertTrue(userScript.source.contains("return 'sdk.ios.popup-bridge://popupbridgev1/';"))
+    }
+
+    func testConstructJavaScriptCompletionResult_whenReturnURLSchemeAndVenmoInstalled_acceptsMerchantSchemeReturn() {
+        let mockURLOpener = MockURLOpener()
+        mockURLOpener.venmoInstalled = true
+
+        let pub = POPPopupBridge(
+            webView: WKWebView(),
+            webAuthenticationSession: mockWebAuthenticationSession,
+            returnURLScheme: "my-app-scheme",
+            application: mockURLOpener
+        )
+
+        // The return validation keys off the effective (merchant) scheme, so a merchant-scheme return
+        // from the Venmo app is accepted and completed.
+        let result = pub.constructJavaScriptCompletionResult(
+            returnURL: URL(string: "my-app-scheme://popupbridgev1/return?token=abc")!
+        )
+        XCTAssertNotNil(result)
+        XCTAssertTrue(result!.contains("window.popupBridge.onComplete(null,"))
+    }
+
+    func testConstructJavaScriptCompletionResult_whenReturnURLSchemeAndVenmoInstalled_rejectsSDKSchemeReturn() {
+        let mockURLOpener = MockURLOpener()
+        mockURLOpener.venmoInstalled = true
+
+        let pub = POPPopupBridge(
+            webView: WKWebView(),
+            webAuthenticationSession: mockWebAuthenticationSession,
+            returnURLScheme: "my-app-scheme",
+            application: mockURLOpener
+        )
+
+        // When the merchant scheme is the effective scheme, the SDK's internal scheme is no longer a
+        // valid return for this instance.
+        let result = pub.constructJavaScriptCompletionResult(
+            returnURL: URL(string: "sdk.ios.popup-bridge://popupbridgev1/return")!
+        )
+        XCTAssertNil(result)
+    }
 }