Updated ViewController with CDP support for WKWebView

Author: mlion-cb

standalone-sample/ios-native-wkwebview/README.md

@@ -1,30 +1,27 @@
 # Coinbase Apple Pay iOS Demo
 
-Minimal working implementation of Coinbase Apple Pay Onramp for native iOS apps using WKWebView.
+Minimal working example of Coinbase Apple Pay integration for native iOS apps using WKWebView.
 
 ## Video Demo
 
-
 https://github.com/user-attachments/assets/ee734f06-3292-4874-8113-b8a360370b6e
 
-
-
 ## Project Structure
 
 ```
 iOS/                        # Native iOS Swift app
-├── ViewController.swift    # Main: WKWebView + postMessage bridge
+├── ViewController.swift    # WKWebView implementation
 ├── AppDelegate.swift
 ├── SceneDelegate.swift
 ├── Info.plist             # Network security config
 └── project.yml            # XcodeGen config
 
-web/                       # Backend + Web interface
-├── server.js              # Express API
+web/                       # Backend server + Web testing
+├── server.js              # Express API to create payment orders
 ├── public/
-│   ├── index.html
+│   ├── index.html        # Web testing interface
 │   └── app.js
-└── .env.example           # API credentials template
+└── .env.example          # API credentials template
 ```
 
 ## Quick Start
@@ -37,7 +34,7 @@ npm install
 cp .env.example .env
 ```
 
-Edit `.env` and add your Coinbase CDP API credentials:
+Edit `.env` and add your [Coinbase CDP API credentials](https://portal.cdp.coinbase.com):
 ```
 CDP_API_KEY_ID=your_api_key_id
 CDP_API_KEY_SECRET=your_api_key_secret
@@ -48,33 +45,30 @@ Start server:
 npm start
 ```
 
-**Web Testing:** Open `http://localhost:3000` in your browser to test the Apple Pay flow using the iframe method (displays QR code fallback for web).
+**Optional:** Test in browser at `http://localhost:3000` (shows QR code for web)
 
 ### 2. iOS App Setup
 
 **Option A: Same WiFi Network**
 
-1. Find your computer's IP address:
-   ```bash
-   ifconfig | grep "inet " | grep -v 127.0.0.1
-   ```
+Find your computer's IP address:
+```bash
+ifconfig | grep "inet " | grep -v 127.0.0.1
+```
 
-2. Update `ViewController.swift` line 153:
-   ```swift
-   let backendURL = "http://YOUR_IP_ADDRESS:3000/api/create-order"
-   ```
+Update `ViewController.swift` line 153:
+```swift
+let backendURL = "http://YOUR_IP_ADDRESS:3000/api/create-order"
+```
 
 **Option B: Using ngrok (Recommended)**
 
 ```bash
-# Install ngrok
 brew install ngrok
-
-# Create tunnel
 ngrok http 3000
 ```
 
-Update `ViewController.swift` line 153 with the ngrok URL:
+Update `ViewController.swift` line 153:
 ```swift
 let backendURL = "https://your-ngrok-url.ngrok-free.dev/api/create-order"
 ```
@@ -86,62 +80,117 @@ let backendURL = "https://your-ngrok-url.ngrok-free.dev/api/create-order"
 3. Select your device in Xcode
 4. Build & Run (⌘R)
 
-**Note:** Apple Pay requires a physical iOS device with Apple Pay support and setup It will not work in the simulator.
+**Note:** Requires a physical iOS device with Apple Pay configured. Won't work in simulator.
 
 ## Requirements
 
 - macOS with Xcode 14+
 - Node.js 16+
-- iOS 14.0+ device with Apple Pay configured
+- Physical iOS device (iOS 14.0+) with Apple Pay set up
 - [Coinbase CDP API credentials](https://portal.cdp.coinbase.com)
 
-## Key Implementation Details
+## How It Works
+
+### 1. Create Payment Order
 
-### WKWebView Configuration
+Your backend calls the Coinbase API to create an order and receive a payment URL:
+
+```javascript
+// Backend calls Coinbase
+const response = await fetch('https://api.cdp.coinbase.com/platform/v2/onramp/orders', {
+    method: 'POST',
+    body: JSON.stringify({
+        paymentAmount: "20",
+        paymentCurrency: "USD",
+        purchaseCurrency: "USDC",
+        paymentMethod: "GUEST_CHECKOUT_APPLE_PAY",
+        // ... other fields
+    })
+});
+
+// Returns: { paymentLink: { url: "https://pay.coinbase.com/..." } }
+```
+
+### 2. Configure WKWebView
+
+Set up WKWebView with the message handler:
 
 ```swift
+// Configure WKWebView
 let configuration = WKWebViewConfiguration()
-configuration.allowsInlineMediaPlayback = true
-configuration.mediaTypesRequiringUserActionForPlayback = []
 
+// Register message handler to receive payment events
 let contentController = WKUserContentController()
-contentController.add(self, name: "onramp")
+contentController.add(self, name: "cbOnramp")  // Must be "cbOnramp"
 configuration.userContentController = contentController
+
+// Create WKWebView
+webView = WKWebView(frame: .zero, configuration: configuration)
 ```
 
-### Coinbase Event Handling
+### 3. Load Payment URL
+
+```swift
+// Load the payment URL from Coinbase
+let url = URL(string: paymentLink)
+webView.load(URLRequest(url: url))
+```
+
+### 4. Receive Payment Events
+
+Coinbase detects `window.webkit.messageHandlers.cbOnramp` and sends events directly:
+
+```swift
+extension ViewController: WKScriptMessageHandler {
+    func userContentController(_ userContentController: WKUserContentController,
+                              didReceive message: WKScriptMessage) {
+        guard message.name == "cbOnramp" else { return }
+
+        // Parse event
+        if let messageBody = message.body as? String,
+           let data = messageBody.data(using: .utf8),
+           let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+           let eventName = json["eventName"] as? String {
+            print("Payment event: \(eventName)")
+            handlePaymentEvent(eventName, data: json)
+        }
+    }
+}
+```
 
-The app listens for these events via `WKScriptMessageHandler`:
+## Payment Events
 
-- See all events [here](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/apple-pay-onramp-api#post-message-events)
+The payment flow sends various events like `onramp_api.load_success`, `onramp_api.commit_success`, `onramp_api.polling_success`, etc.
 
-See `ViewController.swift` lines 357-410 for full implementation.
+See the [full list of events](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/apple-pay-onramp-api#post-message-events) in the Coinbase documentation.
 
 ## Sandbox Testing
 
-The demo uses sandbox mode by default. Transactions use test credentials and won't charge real money.
+The demo uses sandbox mode (no real money):
+- `partnerUserRef` must start with `"sandbox-"`
+- Transactions auto-complete
 
 ## Troubleshooting
 
 **"Internet connection appears to be offline"**
-- Ensure iPhone and computer are on the same WiFi
+- Ensure iPhone and Mac are on same WiFi
+- Try ngrok instead of local IP
 - Check firewall settings
-- Use ngrok to bypass network issues
 
-**Apple Pay not appearing**
-- Must use physical iOS device (not simulator)
+**Apple Pay sheet doesn't appear**
+- Must use physical device (not simulator)
 - Device must have Apple Pay configured
-- App must be served over HTTPS (use ngrok for testing)
+- Ensure message handler name is exactly `"cbOnramp"`
 
-**Events not being received**
-- Check message handler name is `"onramp"`
-- Verify JavaScript bridge injection in `didFinish` navigation
-- Enable Safari Web Inspector to debug
+**No events received**
+- Handler name must be exactly `"cbOnramp"` (case-sensitive)
+- Check Safari Web Inspector for JavaScript errors
 
 ## Documentation
 
-- [Coinbase Onramp Documentation](https://docs.cdp.coinbase.com/onramp/docs)
+- [Coinbase Onramp API Docs](https://docs.cdp.coinbase.com/onramp/docs)
 - [Apple Pay Onramp API](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/apple-pay-onramp-api)
+- [CDP Portal (API Keys)](https://portal.cdp.coinbase.com)
 
 ## License
 

standalone-sample/ios-native-wkwebview/iOS/ViewController.swift

@@ -89,14 +89,16 @@ class ViewController: UIViewController {
         let configuration = WKWebViewConfiguration()
         configuration.preferences.javaScriptEnabled = true
 
-        // IMPORTANT: Set up message handler for postMessage events
+        // IMPORTANT: Set up message handler for Coinbase events
+        // Coinbase SDK natively supports WKWebView via window.webkit.messageHandlers.cbOnramp
+        // No JavaScript injection needed - events are sent directly to this handler!
         let contentController = WKUserContentController()
-        contentController.add(self, name: "onramp")
+        contentController.add(self, name: "cbOnramp") // Handler name must be "cbOnramp"
         configuration.userContentController = contentController
 
-        // CRITICAL: These settings are required for Apple Pay to work
-        configuration.allowsInlineMediaPlayback = true
-        configuration.mediaTypesRequiringUserActionForPlayback = []
+        // These settings may be required for Apple Pay to work
+        // configuration.allowsInlineMediaPlayback = true
+        // configuration.mediaTypesRequiringUserActionForPlayback = []
 
         // Create hidden webview (will only show Apple Pay sheet, not the web page)
         webView = WKWebView(frame: .zero, configuration: configuration)
@@ -320,33 +322,17 @@ class ViewController: UIViewController {
 
 extension ViewController: WKScriptMessageHandler {
     func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
-        // This is the CRITICAL bridge for receiving postMessage events from the Coinbase web page
-
-        guard message.name == "onramp" else { return }
-
-        // Log the type we're receiving
-        logEvent("📦 Message type: \(type(of: message.body))")
-
-        // Parse the message body
-        // With postMessage override, messages arrive as JSON strings
-        if let messageBody = message.body as? String {
-            // Parse JSON string (standard format from postMessage override)
-            logEvent("🔤 Received as String, parsing JSON...")
-            if let data = messageBody.data(using: .utf8),
-               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
-                handleMessageData(json)
-            }
-        } else if let messageBody = message.body as? [String: Any] {
-            // Fallback for Dictionary format (used by event listener approach if enabled)
-            logEvent("📘 Received as Dictionary directly")
-            handleMessageData(messageBody)
+        // Receive events directly from Coinbase SDK via window.webkit.messageHandlers.cbOnramp
+        guard message.name == "cbOnramp" else { return }
+
+        // Parse the message body (Coinbase sends as JSON string)
+        if let messageBody = message.body as? String,
+           let data = messageBody.data(using: .utf8),
+           let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+           let eventName = json["eventName"] as? String {
+            handleCoinbaseEvent(eventName, data: json)
         }
     }
-
-    private func handleMessageData(_ data: [String: Any]) {
-        guard let eventName = data["eventName"] as? String else { return }
-        handleCoinbaseEvent(eventName, data: data)
-    }
 }
 
 // MARK: - WKNavigationDelegate
@@ -355,61 +341,28 @@ extension ViewController: WKNavigationDelegate {
     func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
         logEvent("📄 WebView page loaded")
 
-        // JavaScript Bridge for Coinbase postMessage Events
-        // Coinbase uses the standard web postMessage API, which doesn't automatically reach native iOS.
-        // This bridge forwards those events to iOS via window.webkit.messageHandlers.
-
+        // ✅ NO JAVASCRIPT INJECTION NEEDED!
+        // Coinbase SDK natively detects window.webkit.messageHandlers.cbOnramp
+        // and sends events directly - no manual bridging required!
+
+        /*
+        // ============================================================================
+        // LEGACY APPROACH - Kept for reference
+        // ============================================================================
+        // Before native WKWebView support, iOS developers had to use JavaScript
+        // to bridge postMessage events to native code. This is no longer needed!
+        //
+        // Old method: Intercept window.postMessage and forward to native
+        //
         let bridgeScript = """
         (function() {
-            // Override window.postMessage to forward events to native iOS
-            // This intercepts postMessage calls at the source (single capture point)
             const originalPostMessage = window.postMessage;
             window.postMessage = function(message, targetOrigin) {
-                // Forward to native iOS via WKWebView message handler
                 if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.onramp) {
                     window.webkit.messageHandlers.onramp.postMessage(message);
                 }
-                // Preserve original web behavior
                 originalPostMessage.apply(window, arguments);
             };
-
-            /*
-            // ALTERNATIVE APPROACH (WILL NOT WORK): Message Event Listener
-            //
-            // This approach listens for postMessage events as they cross iframe boundaries.
-            // However, due to Coinbase's nested iframe architecture, the same event may be
-            // captured multiple times as it propagates through iframe levels, causing:
-            // - Duplicate event processing
-            // - Race conditions in payment flow
-            // - Potential spurious cancel events
-            //
-            // The postMessage override above is preferred as it captures each event exactly
-            // once at its source, avoiding duplicates.
-            //
-            // Only consider this approach if:
-            // - The override doesn't work in your environment
-            // - You need to capture cross-origin iframe messages specifically
-            // - You implement deduplication logic on the native side
-            //
-            window.addEventListener('message', function(event) {
-                // Verify message origin
-                try {
-                    const originUrl = new URL(event.origin);
-                    const allowedHosts = ['pay.coinbase.com', 'coinbase.com'];
-                    const isAllowed = allowedHosts.some(host =>
-                        originUrl.hostname === host || originUrl.hostname.endsWith('.' + host)
-                    );
-                    if (!isAllowed) return;
-                } catch (e) {
-                    return;
-                }
-
-                const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
-                if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.onramp) {
-                    window.webkit.messageHandlers.onramp.postMessage(data);
-                }
-            });
-            */
         })();
         """
 
@@ -420,6 +373,15 @@ extension ViewController: WKNavigationDelegate {
                 self?.logEvent("✅ postMessage bridge injected")
             }
         }
+        //
+        // Issues with this approach:
+        // - Extra code complexity (50+ lines of JavaScript)
+        // - Potential for race conditions if not implemented carefully
+        // - Maintenance burden for developers
+        //
+        // With native support, simply register the "cbOnramp" handler and you're done!
+        // ============================================================================
+        */
     }
 
     func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
@@ -432,4 +394,4 @@ extension ViewController: WKNavigationDelegate {
 
 extension ViewController: WKUIDelegate {
     // This is important for handling alerts and prompts from the web page
-}
+}