Messaging

How messages flow between your iOS app and the web journey.

This guide explains how to send events to the web journey, handle incoming requests, and build request-response flows.

Message Types Overview

GBGBridge uses three message types:

Type	Direction	Purpose
Request	Web → Native	The web journey asks the host to do something. Expects a response.
Response	Native → Web	The host returns the result of a request.
Event	Either direction	An asynchronous notification. No response expected.

All messages share the same envelope structure (BridgeMessage) with a correlationId for pairing requests and responses.

Sending Events to the Web Journey

Events are fire-and-forget messages from the native host to the web journey. Use them to notify the web journey of state changes, user actions, or lifecycle transitions.

// Send a simple event
host.send(event: "host.ready", data: [
    "timestamp": .number(Date().timeIntervalSince1970)
])

// Send an event with structured data
host.send(event: "user.action", data: [
    "action": .string("tapped_help"),
    "screen": .string("document_capture")
])

Common Event Patterns

Event Action	When to Send	Example Data
host.ready	After host initialization completes	{ timestamp }
host.background	App enters background	{}
host.foreground	App returns to foreground	{}
journey.cancel	User taps a cancel/back button	{ reason }
host.orientation	Device orientation changes	{ orientation }

Handling Incoming Requests

When the web journey sends a request, GBGBridge routes it to a registered handler or adds it to pendingRequests.

Using Typed Capability Slots (Recommended)

For capture operations, use the typed slots on BridgeHost. Setting a handler declares support and routes requests automatically:

let host = BridgeHost(hostVersion: "1.0.0")

host.documentCapture.handler = { [weak host] request in
    guard let host else { return .cancelled(reason: "Host deallocated") }
    return await host.documentCapture.awaitCompletion()
}

Complete the request from your camera UI callback:

// Success
host.documentCapture.complete(.document(DocumentCaptureResult(
    imageData: imageData, width: 1920, height: 1080
)))

// Cancellation
host.documentCapture.complete(.cancelled(reason: "User dismissed"))

// Failure
host.documentCapture.complete(.failed(
    code: "CAMERA_DENIED", message: "Permission denied", recoverable: true
))

The SDK encodes CaptureResult into the bridge protocol format automatically. See the Capability Handling Guide for the full SwiftUI integration pattern.

Using Custom Capabilities or BridgeCapabilityHandler

For non-camera capabilities, use registerCustomCapability() or implement BridgeCapabilityHandler:

// Custom capability (closure-based)
host.registerCustomCapability("nfc.read") { request, responder in
    responder.respond(status: .success, data: ["chipRead": .bool(true)], error: nil)
}

// BridgeCapabilityHandler protocol (class-based)
host.register(handler: NFCReadHandler())

Handling Requests via the Delegate

For requests that don’t map to a single handler — or when you want centralized request handling — use BridgeHostDelegate.

class JourneyCoordinator: BridgeHostDelegate {
    func bridgeHost(_ host: BridgeHost, unhandledRequest message: BridgeMessage) {
        switch message.payload.action {
        case "journey.complete":
            let result = message.payload.data?["result"]
            handleJourneyComplete(result: result)

            host.respond(
                to: message.correlationId,
                status: .acknowledged
            )

        default:
            host.respond(
                to: message.correlationId,
                status: .unsupported,
                error: BridgeErrorPayload(
                    code: "UNSUPPORTED_ACTION",
                    message: "Action '\(message.payload.action)' is not supported",
                    recoverable: false
                )
            )
        }
    }

    func bridgeHost(_ host: BridgeHost, didReceive message: BridgeMessage) {
        // Log all messages for debugging
        print("[Bridge] \(message.type.rawValue): \(message.payload.action)")
    }

    private func handleJourneyComplete(result: JSONValue?) {
        // Navigate to results screen, etc.
    }
}

Set the delegate on your host:

let coordinator = JourneyCoordinator()
host.delegate = coordinator

Responding to Pending Requests Manually

If a request arrives with no registered handler, it is stored in pendingRequests. You can respond to it later.

// In a SwiftUI view observing the host
ForEach(host.pendingRequests) { request in
    HStack {
        Text(request.payload.action)
        Button("Approve") {
            host.respond(
                to: request.correlationId,
                status: .success,
                data: ["approved": .bool(true)]
            )
        }
        Button("Deny") {
            host.respond(
                to: request.correlationId,
                status: .cancelled
            )
        }
    }
}

Response Patterns

When responding to a request, you supply a status, optional data, and an optional error payload. The patterns below cover the three response shapes you’ll use most: success-with-data, error, and cancellation.

Success with Data

responder.respond(
    status: .success,
    data: [
        "imageBase64": .string("..."),
        "width": .number(1920),
        "height": .number(1080)
    ],
    error: nil
)

Error with Details

responder.respond(
    status: .error,
    data: nil,
    error: BridgeErrorPayload(
        code: "PERMISSION_DENIED",
        message: "Camera permission was denied by the user",
        recoverable: true  // User can grant permission in Settings
    )
)

User Cancellation

responder.respond(
    status: .cancelled,
    data: nil,
    error: nil
)

Unsupported Action

responder.respond(
    status: .unsupported,
    data: nil,
    error: BridgeErrorPayload(
        code: "NOT_AVAILABLE",
        message: "NFC is not available on this device",
        recoverable: false
    )
)

Acknowledged (Async Processing)

Use .acknowledged when the operation will take time and you want to inform the web journey that the request was received.

// First, acknowledge receipt
responder.respond(
    status: .acknowledged,
    data: ["estimatedDuration": .number(5000)],
    error: nil
)

// Later, send the actual result as an event
host.send(event: "camera.capture.complete", data: [
    "imageBase64": .string("..."),
    "correlationId": .string(request.correlationId)
])

Observing All Messages

Use BridgeHostDelegate.bridgeHost(_:didReceive:) to observe every message, or subscribe to the receivedMessages publisher via Combine.

// Combine approach
host.$receivedMessages
    .sink { messages in
        print("Total messages: \(messages.count)")
    }
    .store(in: &cancellables)

// Filter for specific actions
host.$receivedMessages
    .map { messages in
        messages.filter { $0.payload.action == "journey.progress" }
    }
    .sink { progressMessages in
        // Update progress UI
    }
    .store(in: &cancellables)

Error Handling

Bridge messaging can fail in three distinct places: when GBGBridge can’t decode an incoming message, when no WebView is attached to receive an outgoing one, and when JavaScript evaluation in the WebView itself errors out. Each surfaces through lastError so you can react in your UI.

Encoding/Decoding Errors

If GBGBridge cannot decode an incoming message, lastError is set with a description. The message is not added to receivedMessages.

WebView Not Attached

If you call send(event:data:) or respond(to:...) before attaching a WebView, lastError is set to "WebView not attached".

JavaScript Evaluation Errors

If the JavaScript evaluation fails (e.g., the web page has navigated away or the receive() function is not defined), lastError is set with the WebKit error description.

Monitor errors reactively:

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

Next Steps

• Capability Handling Guide — Build handlers for camera, NFC, and other features
• Embedding Guide — SwiftUI and UIKit integration patterns
• API Reference — Detailed method signatures and parameters