iOS Bridge SDK

Embed GBG GO identity verification journeys in your iOS app using the GBGBridge framework.

GBGBridge is a lightweight iOS framework for embedding web-based identity journeys in native apps. It provides a type-safe messaging protocol so web content in a WKWebView can request native capabilities like camera, NFC, and biometrics.

What GBGBridge enables

• Native capability access from web journeys: Web-based identity flows can request camera capture, NFC reads, and other device features through a standardized message protocol.
• Typed capability slots: Declare support for document capture and selfie capture by setting handlers on built-in typed slots. The SDK handles result encoding, busy rejection, and capability query responses automatically.
• Bidirectional messaging: Both the native host and the web content can send and receive structured messages, enabling real-time coordination.
• Capability negotiation with permission state: The web journey can query which native capabilities are available — including camera permission status — before attempting to use them, enabling graceful degradation across environments.
• Drop-in SwiftUI integration: A ready-made BridgeWebView component handles WebView setup, script injection, and message routing with minimal boilerplate. Typed slots expose @Published properties for reactive UI binding.
• Extensible handler architecture: Register custom capability handlers to fulfill any request type the web journey might send, alongside or instead of typed slots.

Architecture at a glance

GBGBridge sits between your iOS app and the web journey, routing structured messages in both directions:

The web journey sends structured JSON messages to the native host via window.webkit.messageHandlers.gbgBridge.postMessage(). The BridgeHost decodes each message, routes requests to registered capability handlers, and sends responses back by evaluating JavaScript on the WebView via window.GBGBridge.receive().

Quick start

The minimum integration is a BridgeHost, a BridgeWebView pointed at your journey URL, and a handler set on the document-capture slot:

import GBGBridge
import SwiftUI

struct JourneyView: View {
    @StateObject private var host = BridgeHost(hostVersion: "1.0.0")

    var body: some View {
        BridgeWebView(
            url: URL(string: "https://journey.example.com")!,
            host: host
        )
        .onAppear {
            // Declare document capture support by setting a handler
            host.documentCapture.handler = { request in
                // Present your camera UI and return a result
                return await host.documentCapture.awaitCompletion()
            }
        }
    }
}

Setting a handler on a typed slot automatically declares the capability as supported. The BridgeWebView handles WebView creation, bootstrap script injection, and message handler registration. Capability query responses — including permission state — are built automatically from the slots you configure.

Requirements

Requirement	Minimum
iOS	15.0
Swift	5.9
Xcode	15.0
Distribution	Swift Package Manager (XCFramework)
Dependencies	None (zero external dependencies)

Documentation map

Document	Description
Tutorial	Build a complete iOS identity verification app from scratch
Getting Started	Step-by-step installation, setup, and first integration
Concepts	Architecture, mental model, terminology, and design rationale
API Reference	Complete reference for every public type, method, and property
Guides
Embedding	Embedding the WebView in SwiftUI and UIKit apps
Messaging	Sending events, handling requests, and response patterns
Capability Handling	Registering handlers, capability queries, and environment negotiation
Security	Security model, content policies, and transport safety
Troubleshooting	Common issues, debugging techniques, and diagnostic tools
FAQ	Frequently asked questions
Examples
Hello Journey	Minimal integration — load a journey and display it
Two-Way Communication	Send events and handle requests bidirectionally
Advanced Integration	Custom config, lifecycle handling, error handling, capability checks

License

See the LICENSE file included with the framework distribution for terms.