Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Diagnostic Tools

​

Observing lastError

// In SwiftUI
Text(host.lastError ?? "No errors")

// Via Combine
host.$lastError
    .compactMap { $0 }
    .sink { error in
        print("[Bridge Error] \(error)")
    }
    .store(in: &cancellables)

​

Message Log

// Print all received messages
for message in host.receivedMessages {
    print("[\(message.type.rawValue)] \(message.payload.action) — \(message.correlationId)")
}

​

Pending Request Inspection

if !host.pendingRequests.isEmpty {
    print("Unhandled requests:")
    for req in host.pendingRequests {
        print("  - \(req.payload.action) (\(req.correlationId))")
    }
}

​

Safari Web Inspector

1. Enable Web Inspector on your device: Settings → Safari → Advanced → Web Inspector.
2. Connect your device to a Mac.
3. In Safari on Mac, go to Develop → [Your Device] → [Your App].
4. Use the console to inspect window.GBGBridge and test message sending.

// In Safari Web Inspector console:
console.log(window.GBGBridge);  // Should show the bridge namespace
console.log(typeof window.GBGBridge.receive);  // Should be "function"

​

Common Issues

​

Messages Not Being Received by the Host

​

Possible causes

1. Wrong message handler name. The web journey must use exactly:
   window.webkit.messageHandlers.gbgBridge.postMessage(message);
   
   Note the lowercase g in gbgBridge.
2. WebView not configured. Ensure you used BridgeWebView or BridgeWebViewConfigurator.configure(_:host:). A plain WKWebView does not have the message handler registered.
3. Bootstrap script not injected. If the web journey tries to send a message before the bootstrap script runs, window.webkit.messageHandlers.gbgBridge may not exist. The bootstrap script runs at document start, but if you’re configuring the WebView after navigation begins, messages may be lost.

​

Messages Not Being Received by the Web Journey

​

Possible causes

1. WebView not attached. Check lastError — it will say "WebView not attached" if the WebView reference was lost.
2. window.GBGBridge.receive not defined. The web journey must replace the no-op receive() with its own implementation. Check from Safari Web Inspector:
   console.log(window.GBGBridge.receive.toString());
   
3. JavaScript evaluation error. Check lastError for messages starting with "evaluateJavaScript failed:".
4. Page navigated away. If the WebView navigated to a different page, the bridge context is lost. The bootstrap script re-runs on each page load, but the web journey must reinitialize its receive() function.

​

Message Decoding Failures

​

Possible causes

1. Malformed JSON. The web journey is sending a message that doesn’t match the BridgeMessage structure.
2. Missing required fields. Every message must have: version, correlationId, type, timestamp, and payload (with at least action).
3. Wrong type for type field. Must be one of: "request", "response", "event".

{
  "version": "1.0",
  "correlationId": "unique-id",
  "type": "request",
  "timestamp": Date.now(),
  "payload": {
    "action": "camera.capture",
    "data": {}
  }
}

​

Capability Query Returns Unexpected Results

​

Possible causes

1. Typed slot without a handler. When using init(hostVersion:), a slot only appears as supported if handler is set and isEnabled is true. If you forgot to set a handler, the slot won’t appear.
2. Slot is disabled. Check that isEnabled hasn’t been set to false on the slot.
3. Capabilities not declared (configuration-based init). When using init(configuration:), only capabilities in the BridgeConfiguration dictionary are reported.
4. Custom capability not registered. If using registerCustomCapability(), ensure it was called before the query.

​

Permission State Not Appearing in Query Response

​

Possible causes

1. Not using typed slots. Permission state is only included automatically when using init(hostVersion:) with typed slots that have permissionState set.
2. CameraDetector not called. The default permissionState is .notDetermined. Call CameraDetector.check() and assign the result.
3. Using configuration-based init without permissionState. The BridgeCapabilityInfo permissionState field defaults to nil. Set it explicitly.

let camera = CameraDetector.check()
host.documentCapture.permissionState = camera.permissionState

​

Handler Not Called for Requests

​

Possible causes

1. Typed slot handler not set. When using init(hostVersion:), ensure host.documentCapture.handler (or selfieCapture.handler) is set. Without a handler, requests for camera.document.capture go to pendingRequests.
2. Action mismatch. For custom capabilities or BridgeCapabilityHandler, the action property must exactly match the request’s payload.action. Check for typos and case sensitivity.
3. Handler not registered. For the register(handler:) path, ensure it was called before the request arrived.
4. Slot is disabled. Check that isEnabled is true on the typed slot.

// Typed slot — action is "camera.document.capture"
host.documentCapture.handler = { ... }

// Protocol-based handler — action must match exactly
let action = "camera.document.capture"  // Must match web journey's payload.action

​

App Transport Security Errors

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

​

WebView Shows Blank Page

​

Possible causes

1. Invalid URL. Check that the URL is reachable.
2. ATS blocking. See above.
3. CORS issues. If the journey loads resources from other domains, check CORS headers.
4. JavaScript error. Connect Safari Web Inspector to check for console errors.

​

Memory Warnings or Crashes

​

Possible causes

1. Large payloads. Sending very large Base64-encoded images through the bridge can cause memory pressure. Consider passing file paths instead of raw data.
2. Message accumulation. receivedMessages grows without bound. If you’re in a long-running session, this array can become large.

// Instead of sending raw image data:
// data: ["imageBase64": .string(largeBase64String)]

// Send a file path:
responder.respond(
    status: .success,
    data: ["imagePath": .string(tempFilePath)],
    error: nil
)

​

SwiftUI View Not Updating

​

Possible causes

1. Using @ObservedObject where @StateObject is needed. If the view owns the host, use @StateObject to prevent re-creation on re-renders.
2. Host created outside the view hierarchy. Ensure the host is referenced via @StateObject or @ObservedObject.

// Owner view — creates the host
struct ParentView: View {
    @StateObject private var host = BridgeHost(...)  // Use @StateObject
    var body: some View {
        ChildView(host: host)
    }
}

// Child view — receives the host
struct ChildView: View {
    @ObservedObject var host: BridgeHost  // Use @ObservedObject
    var body: some View { ... }
}

​

Typed Slot Returns “BUSY” Error

.fullScreenCover(isPresented: $showCamera, onDismiss: {
    if host.documentCapture.activeRequest != nil {
        host.documentCapture.complete(.cancelled(reason: "Dismissed"))
    }
}) { ... }

​

Debugging Checklist

• Check host.lastError for error messages.
• Check host.receivedMessages to see if messages are arriving.
• Check host.pendingRequests for unhandled requests.
• For typed slots: verify handler is set and isSupported is true.
• For typed slots: check activeRequest isn’t stuck — i.e. a previous request didn’t complete.
• Connect Safari Web Inspector to examine the web side.
• Verify handler action strings match request actions exactly.
• Ensure the WebView was configured via BridgeWebView or BridgeWebViewConfigurator.
• Confirm the journey URL is reachable and uses HTTPS.
• Check Info.plist for required permission descriptions.
• Verify @StateObject vs @ObservedObject usage.

​

Next Steps

• FAQ — Common questions
• Messaging Guide — Message flow details
• Security Guide — Security best practices