merging main changes

Author: joaaraujo-paypal

.github/PULL_REQUEST_TEMPLATE.md

@@ -29,9 +29,9 @@
 Internal to PayPal contributors should fill out this section. All others can delete.
 
 PR should follow these steps before codeowners review will begin:
-1. PR should be opened in a draft state with the `tech lead review required`, and `inner source` label
+1. Comment `/inner source` on this PR — this will automatically add the `inner source` and `tech lead review required` labels. Open the PR in a draft state.
 2. PR should be reviewed by and approved by your team's technical lead, we do not allow LGTM reviews, there should be comments and feedback provided on all PR reviews
-3. Once the above steps are completed, the PR can be moved to ready to review with the `tech lead review required` label removed
+3. Once the above steps are completed, comment `/ready` on this PR — this will automatically remove the `tech lead review required` label. Move the PR to ready to review.
 4. PR comments must be addressed within 24 hours, if you are unable to address within this timeframe, move the PR back to a draft state so our team knows not to review
 
 ### Inner Source Checklist

.github/workflows/inner-source-labels.yml

@@ -0,0 +1,75 @@
+name: Inner Source Labels
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  add-inner-source-labels:
+    # Only fires on PR comments (not plain issues) containing the slash command
+    if: >
+      github.event.issue.pull_request != null &&
+      contains(github.event.comment.body, '/inner source')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acknowledge command
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes'
+            });
+
+      - name: Add inner source labels
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['inner source', 'tech lead review required']
+            });
+
+  remove-tech-lead-label:
+    # Only fires on PR comments containing the slash command
+    if: >
+      github.event.issue.pull_request != null &&
+      contains(github.event.comment.body, '/ready')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acknowledge command
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes'
+            });
+
+      - name: Remove tech lead review required label
+        uses: actions/github-script@v7
+        with:
+          script: |
+            try {
+              await github.rest.issues.removeLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                name: 'tech lead review required'
+              });
+            } catch (e) {
+              // 404 means the label wasn't on the PR — that's fine
+              if (e.status !== 404) throw e;
+            }

.github/workflows/release.yml

@@ -14,6 +14,7 @@ jobs:
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
 
       - name: Use Xcode 16.4.0
         run: sudo xcode-select -switch /Applications/Xcode_16.4.0.app

CHANGELOG.md

@@ -1,10 +1,12 @@
 # PopupBridge iOS Release Notes
 
 ## unreleased
-
 * Add support for the PayPal app switch flow. When enabled, checkout launches the native PayPal app and falls back to `ASWebAuthenticationSession` if the launch fails. Requires additional `SceneDelegate` integration — see the README.
 * Add a `POPPopupBridge` initializer that takes a `returnURLScheme` to enable the PayPal app switch flow.
 
+## 3.1.0 (2026-06-24)
+* 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

@@ -15,9 +15,22 @@
 	<key>CFBundlePackageType</key>
 	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
 	<key>CFBundleShortVersionString</key>
-	<string>3.0.0</string>
+	<string>3.1.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>CFBundleVersion</key>
-	<string>3.0.0</string>
+	<string>3.1.0</string>
 	<key>CFBundleURLTypes</key>
 	<array>
 		<dict>

PopupBridge.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'PopupBridge'
-  s.version          = "3.0.0"
+  s.version          = "3.1.0"
   s.summary          = 'Use PopupBridge to enable your web view to open pages in a Safari View Controller'
   s.description      = <<-DESC
 PopupBridge is an iOS library that allows WKWebViews to open popup windows in an SFSafariViewController

README.md

@@ -57,6 +57,30 @@ To enable PayPal installation detection (`window.popupBridge.isPayPalInstalled`)
 </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

@@ -15,6 +15,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
     private let messageHandlerName = "POPPopupBridge"
     private let sessionID = UUID().uuidString.replacingOccurrences(of: "-", with: "")
     private let webView: WKWebView
+    private let returnURLScheme: String?
     private var application: URLOpener = UIApplication.shared
 
     private var webAuthenticationSession: WebAuthenticationSession = WebAuthenticationSession()
@@ -24,6 +25,19 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
     /// keeping `POPPopupBridge` a coordinator.
     private var appSwitchHandler: PayPalAppSwitchHandler?
 
+    /// 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 for the standard browser-based checkout flow.
@@ -49,12 +63,19 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
         )
     }
 
-    /// Initialize a Popup Bridge with the native PayPal app switch flow enabled.
+    /// Initialize a Popup Bridge with a `returnURLScheme` to enable the native app switch flows.
     ///
-    /// Use this initializer to let the SDK launch the native PayPal app for checkout instead of opening a
-    /// browser. Because the deep-link return arrives at the host app's `SceneDelegate` (outside the
+    /// Use this initializer to let the SDK launch a native app for checkout instead of opening a
+    /// browser. Because a deep-link return arrives at the host app's `SceneDelegate` (outside the
     /// WebView), a `returnURLScheme` is **required** — there is no flag to toggle and no scheme guessing.
     ///
+    /// The same `returnURLScheme` drives both native app switch flows:
+    /// - **PayPal:** the SDK launches the native PayPal app and the return URL arrives at the host
+    ///   app's `SceneDelegate` (see the required integration below).
+    /// - **Venmo:** when the Venmo app is installed, the flow app switches into the Venmo app, which
+    ///   deep-links back via this scheme. The scheme is then advertised to the JavaScript layer as the
+    ///   return URL prefix (instead of the SDK's internal ASWeb callback scheme).
+    ///
     /// **Required SceneDelegate integration:** the host app must forward incoming URLs from its
     /// `SceneDelegate` to PopupBridge via `PopupBridgeAppContextSwitcher.shared.handleReturnURL(_:)`,
     /// otherwise the checkout flow will hang indefinitely after the PayPal app returns. The method
@@ -69,10 +90,10 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
     /// - 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 in the app's `Info.plist` that PopupBridge uses as
-    ///   the return URL for the checkout flow. PopupBridge does not guess the scheme from
-    ///   `CFBundleURLTypes`, since apps that register multiple URL schemes (e.g. Facebook, Google
-    ///   Sign-In) would resolve the wrong one.
+    ///   - returnURLScheme: The URL scheme registered under `CFBundleURLTypes` in the app's `Info.plist`
+    ///   that PopupBridge uses as the return URL for the checkout flow. PopupBridge does not guess the
+    ///   scheme from `CFBundleURLTypes`, since apps that register multiple URL schemes (e.g. Facebook,
+    ///   Google Sign-In) would resolve the wrong one.
     ///   - 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`.
@@ -92,15 +113,16 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
 
     /// Exposed for testing.
     ///
-    /// Designated initializer that injects a custom `WebAuthenticationSession` so tests can stub the
-    /// browser authentication flow. Pass `returnURLScheme` and a mocked `URLOpener` to exercise the
-    /// PayPal app switch flow end to end; omit them to test the standard browser flow with app switch
-    /// disabled.
+    /// Designated initializer that injects a custom `WebAuthenticationSession` and `URLOpener` so tests
+    /// can stub the browser authentication flow and simulate whether the PayPal/Venmo apps are
+    /// installed. Pass `returnURLScheme` and a mocked `URLOpener` to exercise the native app switch
+    /// flows end to end; omit them to test the standard browser flow with app switch disabled.
     ///
-    /// A non-`nil` `returnURLScheme` selects the PayPal app switch flow; when it is `nil`, the standard
+    /// A non-`nil` `returnURLScheme` enables the native app switch flows; when it is `nil`, the standard
     /// browser-based flow is used and the native app switch path stays disabled. Kept `internal` so the
-    /// only public entry points are the two flow-specific initializers above, keeping the internal
-    /// `URLOpener` out of the public API.
+    /// 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,
@@ -111,6 +133,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
         self.webView = webView
         self.application = application
         self.webAuthenticationSession = webAuthenticationSession
+        self.returnURLScheme = returnURLScheme
 
         super.init()
 
@@ -119,6 +142,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
         }
         configureWebView()
         self.webAuthenticationSession.prefersEphemeralWebBrowserSession = prefersEphemeralWebBrowserSession
+        self.webAuthenticationSession.callbackURLScheme = returnURLPrefixScheme
 
         returnBlock = { [weak self] url in
             guard let script = self?.constructJavaScriptCompletionResult(returnURL: url) else {
@@ -161,7 +185,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(PopupBridgeConstants.host) == .orderedSame
         else {
             return nil
@@ -197,7 +221,7 @@ public class POPPopupBridge: NSObject, WKScriptMessageHandler {
         let isPayPalAppSwitchAvailable = appSwitchHandler?.isPayPalAppInstalled() ?? false
 
         let javascript = PopupBridgeUserScript(
-            scheme: PopupBridgeConstants.callbackURLScheme,
+            scheme: returnURLPrefixScheme,
             scriptMessageHandlerName: messageHandlerName,
             host: PopupBridgeConstants.host,
             isVenmoInstalled: application.isVenmoAppInstalled(),

Sources/PopupBridge/PopupBridge-Framework-Info.plist

@@ -15,9 +15,9 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>3.0.0</string>
+	<string>3.1.0</string>
 	<key>CFBundleVersion</key>
-	<string>3.0.0</string>
+	<string>3.1.0</string>
 	<key>NSPrincipalClass</key>
 	<string></string>
 </dict>

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()