Advanced integration - GBG Documentation

A production-style integration demonstrating custom configuration, lifecycle management, error handling, capability negotiation, and graceful degradation for environment-sensitive features like passport chip reading.

What this example demonstrates

Typed capability slots for document capture with CameraDetector permission state
Passport chip reading with the host.nfcRead typed slot (GBGBridge 1.2.0 or later)
Runtime capability detection with pre-launch validation
CaptureResult-based response encoding (no manual JSONValue dictionaries)
Lifecycle management (background/foreground events)
Delegate-based message observation and routing
Graceful degradation for unsupported capabilities

Complete source

The full app below is a single SwiftUI target that demonstrates pre-launch capability validation, typed slots for document capture and passport chip reading, lifecycle event forwarding, and delegate-based message observation. Read through the section markers (// MARK: -) to navigate; each block is the production-style version of a pattern shown elsewhere in the docs.

import Combine
import CoreNFC
import GBGBridge
import SwiftUI

// MARK: - App Entry Point

@main
struct AdvancedApp: App {
    var body: some Scene {
        WindowGroup {
            JourneyLauncherView()
        }
    }
}

// MARK: - Journey Configuration

/// Centralized configuration for the identity verification journey.
struct JourneyConfig {
    let url: URL
    let requiredCapabilities: [String]
    let hostVersion: String

    static let passportVerification = JourneyConfig(
        url: URL(string: "https://journey.example.com/passport")!,
        requiredCapabilities: ["camera.document", "document.nfc"],
        hostVersion: "1.0.0"
    )

    static let documentOnly = JourneyConfig(
        url: URL(string: "https://journey.example.com/document")!,
        requiredCapabilities: ["camera.document"],
        hostVersion: "1.0.0"
    )
}

// MARK: - Journey Launcher (Pre-launch Validation)

struct JourneyLauncherView: View {
    @State private var selectedJourney: JourneyConfig = .passportVerification
    @State private var showJourney = false
    @State private var showCapabilityWarning = false

    private let deviceCapabilities = DeviceCapabilities.detect()

    var body: some View {
        NavigationStack {
            VStack(spacing: 24) {
                Text("Identity Verification")
                    .font(.title2)
                    .fontWeight(.semibold)

                // Journey selection
                VStack(spacing: 12) {
                    JourneyOptionButton(
                        title: "Passport Verification",
                        subtitle: "Document + passport chip read",
                        requirements: ["camera.document", "document.nfc"],
                        deviceCapabilities: deviceCapabilities
                    ) {
                        selectedJourney = .passportVerification
                        attemptLaunch()
                    }

                    JourneyOptionButton(
                        title: "Document Verification",
                        subtitle: "Document capture only",
                        requirements: ["camera.document"],
                        deviceCapabilities: deviceCapabilities
                    ) {
                        selectedJourney = .documentOnly
                        attemptLaunch()
                    }
                }
                .padding(.horizontal)

                // Device capability summary
                DeviceCapabilitySummary(capabilities: deviceCapabilities)

                Spacer()
            }
            .padding(.top, 32)
            .navigationTitle("Verification")
            .navigationBarTitleDisplayMode(.inline)
            .fullScreenCover(isPresented: $showJourney) {
                JourneyContainerView(config: selectedJourney)
            }
            .alert("Capability Warning", isPresented: $showCapabilityWarning) {
                Button("Continue Anyway") {
                    showJourney = true
                }
                Button("Cancel", role: .cancel) {}
            } message: {
                let missing = missingCapabilities(for: selectedJourney)
                Text("This journey requires \(missing.joined(separator: ", ")) which \(missing.count == 1 ? "is" : "are") not available on this device. The journey may not complete successfully.")
            }
        }
    }

    private func attemptLaunch() {
        let missing = missingCapabilities(for: selectedJourney)
        if missing.isEmpty {
            showJourney = true
        } else {
            showCapabilityWarning = true
        }
    }

    private func missingCapabilities(for journey: JourneyConfig) -> [String] {
        journey.requiredCapabilities.filter { capability in
            deviceCapabilities.isSupported(capability) != true
        }
    }
}

// MARK: - Device Capabilities Detection

struct DeviceCapabilities {
    let nfcAvailable: Bool
    let cameraResult: CameraDetector.Result

    static func detect() -> DeviceCapabilities {
        DeviceCapabilities(
            nfcAvailable: NFCTagReaderSession.readingAvailable,
            cameraResult: CameraDetector.check()
        )
    }

    func isSupported(_ capability: String) -> Bool {
        switch capability {
        case "camera.document": return cameraResult.hardwareAvailable
        case "document.nfc": return nfcAvailable
        default: return false
        }
    }
}

// MARK: - Journey Container (Full Integration)

struct JourneyContainerView: View {
    let config: JourneyConfig

    @StateObject private var host: BridgeHost
    @StateObject private var coordinator = JourneyCoordinator()
    @Environment(\.dismiss) private var dismiss
    @State private var journeyState: JourneyState = .loading
    @State private var showDocumentCamera = false
    @State private var showChipReader = false

    init(config: JourneyConfig) {
        self.config = config
        _host = StateObject(wrappedValue: BridgeHost(hostVersion: config.hostVersion))
    }

    var body: some View {
        NavigationStack {
            ZStack {
                // Journey WebView
                BridgeWebView(url: config.url, host: host)
                    .opacity(journeyState == .active ? 1 : 0)

                // Loading overlay
                if journeyState == .loading {
                    ProgressView("Loading verification...")
                }

                // Error overlay
                if case .error(let message) = journeyState {
                    JourneyErrorView(message: message) {
                        journeyState = .loading
                        // WebView will reload via URL change mechanism
                    }
                }

                // Completion overlay
                if case .completed(let result) = journeyState {
                    JourneyCompleteView(result: result) {
                        dismiss()
                    }
                }
            }
            .navigationTitle("Verification")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .navigationBarLeading) {
                    Button("Cancel") {
                        host.send(event: "journey.cancel", data: [
                            "reason": .string("user_dismissed")
                        ])
                        dismiss()
                    }
                }
            }
            .onAppear { setupBridge() }
            // Present the chip reader while a chip read is active
            .onChange(of: host.nfcRead.activeRequest) { request in
                showChipReader = request != nil
            }
            .sheet(isPresented: $showChipReader, onDismiss: {
                host.nfcRead.cancelIfBusy(reason: "User dismissed the chip reader")
            }) {
                if let request = host.nfcRead.activeRequest {
                    ChipReaderView(request: request) { result in
                        host.nfcRead.complete(result)
                        showChipReader = false
                    }
                }
            }
            .onReceive(NotificationCenter.default.publisher(for: UIApplication.willResignActiveNotification)) { _ in
                host.send(event: "host.background", data: [:])
            }
            .onReceive(NotificationCenter.default.publisher(for: UIApplication.didBecomeActiveNotification)) { _ in
                host.send(event: "host.foreground", data: [:])
            }
        }
    }

    private func setupBridge() {
        // Set delegate
        host.delegate = coordinator
        coordinator.onStateChange = { [weak coordinator] newState in
            Task { @MainActor in
                journeyState = newState
            }
        }

        let capabilities = DeviceCapabilities.detect()

        // Set up typed slot for document capture
        if capabilities.cameraResult.hardwareAvailable {
            host.documentCapture.handler = { [weak host] request in
                guard let host else { return .cancelled(reason: "Host deallocated") }
                return await host.documentCapture.awaitCompletion()
            }
            host.documentCapture.permissionState = capabilities.cameraResult.permissionState
        }

        // Set up the typed slot for passport chip reading. The SDK validates the
        // request, answers BUSY and UNSUPPORTED, and builds the response.
        // deviceCanRead defaults to false: without it, chip reading is reported unsupported.
        host.nfcRead.deviceCanRead = { NFCTagReaderSession.readingAvailable }
        host.nfcRead.handler = { [weak host] _ in
            await host?.nfcRead.awaitCompletion() ?? .cancelled(reason: "Host deallocated")
        }

        // Mark as active after a brief delay (allows WebView to initialize)
        Task {
            try? await Task.sleep(nanoseconds: 500_000_000)
            await MainActor.run {
                if journeyState == .loading {
                    journeyState = .active
                }
            }
        }
    }
}

// MARK: - Journey State

enum JourneyState: Equatable {
    case loading
    case active
    case completed(JourneyResult)
    case error(String)

    static func == (lhs: JourneyState, rhs: JourneyState) -> Bool {
        switch (lhs, rhs) {
        case (.loading, .loading), (.active, .active): return true
        case (.completed(let a), .completed(let b)): return a.status == b.status
        case (.error(let a), .error(let b)): return a == b
        default: return false
        }
    }
}

struct JourneyResult {
    let status: String
    let referenceId: String?
}

// MARK: - Journey Coordinator (Delegate)

@MainActor
final class JourneyCoordinator: ObservableObject, BridgeHostDelegate {
    var onStateChange: ((JourneyState) -> Void)?

    func bridgeHost(_ host: BridgeHost, didReceive message: BridgeMessage) {
        // Monitor for journey lifecycle events
        switch message.payload.action {
        case "journey.started":
            onStateChange?(.active)

        case "journey.complete":
            let status = extractString(from: message.payload.data, key: "status") ?? "unknown"
            let refId = extractString(from: message.payload.data, key: "referenceId")
            onStateChange?(.completed(JourneyResult(status: status, referenceId: refId)))

        case "journey.error":
            let errorMsg = extractString(from: message.payload.data, key: "message") ?? "An error occurred"
            onStateChange?(.error(errorMsg))

        default:
            break
        }
    }

    func bridgeHost(_ host: BridgeHost, unhandledRequest message: BridgeMessage) {
        // Respond to unknown requests with unsupported
        host.respond(
            to: message.correlationId,
            status: .unsupported,
            error: BridgeErrorPayload(
                code: "UNSUPPORTED_ACTION",
                message: "Action '\(message.payload.action)' is not supported by this host",
                recoverable: false
            )
        )
    }

    private func extractString(from data: [String: JSONValue]?, key: String) -> String? {
        guard let value = data?[key], case .string(let str) = value else { return nil }
        return str
    }
}

// MARK: - Supporting Views

struct JourneyOptionButton: View {
    let title: String
    let subtitle: String
    let requirements: [String]
    let deviceCapabilities: DeviceCapabilities
    let action: () -> Void

    private var allRequirementsMet: Bool {
        requirements.allSatisfy { deviceCapabilities.isSupported($0) }
    }

    var body: some View {
        Button(action: action) {
            HStack {
                VStack(alignment: .leading, spacing: 4) {
                    Text(title)
                        .font(.headline)
                        .foregroundColor(.primary)
                    Text(subtitle)
                        .font(.caption)
                        .foregroundColor(.secondary)
                }
                Spacer()
                if allRequirementsMet {
                    Image(systemName: "checkmark.circle.fill")
                        .foregroundColor(.green)
                } else {
                    Image(systemName: "exclamationmark.triangle.fill")
                        .foregroundColor(.orange)
                }
            }
            .padding()
            .background(Color(.secondarySystemGroupedBackground))
            .cornerRadius(12)
        }
    }
}

struct DeviceCapabilitySummary: View {
    let capabilities: DeviceCapabilities

    var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            Text("Device Capabilities")
                .font(.caption)
                .fontWeight(.semibold)
                .foregroundColor(.secondary)

            HStack(spacing: 16) {
                CapabilityBadge(name: "Camera", available: capabilities.cameraResult.hardwareAvailable)
                CapabilityBadge(name: "Chip reader", available: capabilities.nfcAvailable)
            }
        }
        .padding(.horizontal)
    }
}

struct CapabilityBadge: View {
    let name: String
    let available: Bool

    var body: some View {
        HStack(spacing: 4) {
            Image(systemName: available ? "checkmark.circle.fill" : "xmark.circle.fill")
                .foregroundColor(available ? .green : .red)
                .font(.caption)
            Text(name)
                .font(.caption)
                .foregroundColor(.primary)
        }
        .padding(.horizontal, 10)
        .padding(.vertical, 4)
        .background(
            Capsule()
                .fill(available ? Color.green.opacity(0.1) : Color.red.opacity(0.1))
        )
    }
}

struct JourneyErrorView: View {
    let message: String
    let onRetry: () -> Void

    var body: some View {
        VStack(spacing: 16) {
            Image(systemName: "exclamationmark.triangle")
                .font(.system(size: 48))
                .foregroundColor(.orange)
            Text("Verification Error")
                .font(.title3)
                .fontWeight(.semibold)
            Text(message)
                .multilineTextAlignment(.center)
                .foregroundColor(.secondary)
            Button("Retry") {
                onRetry()
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
    }
}

struct JourneyCompleteView: View {
    let result: JourneyResult
    let onDismiss: () -> Void

    var body: some View {
        VStack(spacing: 16) {
            Image(systemName: result.status == "success" ? "checkmark.circle.fill" : "xmark.circle.fill")
                .font(.system(size: 64))
                .foregroundColor(result.status == "success" ? .green : .red)
            Text(result.status == "success" ? "Verification Complete" : "Verification Failed")
                .font(.title3)
                .fontWeight(.semibold)
            if let refId = result.referenceId {
                Text("Reference: \(refId)")
                    .font(.caption)
                    .foregroundColor(.secondary)
            }
            Button("Done") {
                onDismiss()
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
    }
}

/// Your chip reader. Run a reader such as the SmartCapture Ozone reader and hand back
/// what it read. See Capability Handling > Passport Chip Reading for the Ozone mapping.
struct ChipReaderView: View {
    let request: NfcReadRequest
    let onResult: (NfcReadResult) -> Void

    var body: some View {
        // Replace with your reader UI
        Button("Cancel") {
            onResult(.cancelled(reason: "User cancelled the chip read"))
        }
    }
}

// Note: CameraDetector (from GBGBridge) handles AVFoundation imports internally

Architecture overview

Key patterns demonstrated

Pre-launch capability validation

Before starting the journey, the launcher checks whether all required capabilities are available:

let missing = journey.requiredCapabilities.filter { capability in
    deviceCapabilities.isSupported(capability) != true
}

if missing.isEmpty {
    showJourney = true
} else {
    showCapabilityWarning = true  // Let user choose to continue or cancel
}

This prevents users from starting a journey that will fail partway through due to missing hardware.

Lifecycle events

The app sends events when entering background and returning to foreground. The web journey can use these to pause/resume timers, save state, or handle session timeouts.

.onReceive(NotificationCenter.default.publisher(for: UIApplication.willResignActiveNotification)) { _ in
    host.send(event: "host.background", data: [:])
}

Permission state with CameraDetector

CameraDetector.check() detects hardware and permission status. The result is assigned to the typed slot’s permissionState, which is automatically included in capability query responses:

let capabilities = DeviceCapabilities.detect()
host.documentCapture.permissionState = capabilities.cameraResult.permissionState

The web journey can now check permissionState before attempting capture and prompt the user to grant access if needed.

Typed Slots

This example uses a typed slot for each capability:

Document capture uses host.documentCapture. The SDK handles result encoding and busy rejection automatically.
Passport chip reading uses host.nfcRead. The handler waits for the reader sheet, and the SDK validates the request and builds the chip response. Don’t build that response yourself.

For capabilities without a typed slot, see Custom Capability Registration.

Graceful Degradation

Chip reading is detected at runtime with NFCTagReaderSession.readingAvailable. If it’s not available, the launcher shows a warning, and deviceCanRead makes the slot report document.nfc as unsupported. Chip reading has no web fallback, so the journey then asks the person to use a different device.

Running this example

To run the example end-to-end, follow these setup steps:

Add GBGBridge 1.2.0 or later via SPM.

Add to Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera is used for document capture during identity verification.</string>
<key>NFCReaderUsageDescription</key>
<string>NFC is used to read the chip in your passport.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
</array>

For chip reading: Add the Near Field Communication Tag Reading capability.
Update journeyURL to your web journey endpoint.
Build and run.

Next steps

Capability Handling Guide — Deep dive on capability patterns
Security Guide — Production security checklist
API Reference — Complete type reference

​What this example demonstrates

​Complete source

​Architecture overview

​Key patterns demonstrated

​Pre-launch capability validation

​Lifecycle events

​Permission state with CameraDetector

​Typed Slots

​Graceful Degradation

​Running this example

​Next steps