> ## 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.

# 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:

```mermaid theme={null}
graph TB
    subgraph Host["iOS Host Application"]
        BH[BridgeHost<br/>message router]
        CH[Capability Handlers<br/>camera · NFC · custom]
        WV[WKWebView<br/>BridgeWebView / Configurator]
        BH <--> CH
        BH <--> WV
    end
    Web["Web Journey (JavaScript)"]
    WV -- "evaluateJavaScript<br/>window.GBGBridge.receive" --> Web
    Web -- "postMessage<br/>webkit.messageHandlers.gbgBridge" --> WV
```

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:

```swift theme={null}
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](/docs/go-v2/developer-integration/sdks/ios/tutorial)                                    | Build a complete iOS identity verification app from scratch           |
| [Getting Started](/docs/go-v2/developer-integration/sdks/ios/getting-started)                      | Step-by-step installation, setup, and first integration               |
| [Concepts](/docs/go-v2/developer-integration/sdks/ios/concepts)                                    | Architecture, mental model, terminology, and design rationale         |
| [API Reference](/docs/go-v2/developer-integration/sdks/ios/api-reference)                          | Complete reference for every public type, method, and property        |
| **Guides**                                                                                         |                                                                       |
| [Embedding](/docs/go-v2/developer-integration/sdks/ios/embedding)                                  | Embedding the WebView in SwiftUI and UIKit apps                       |
| [Messaging](/docs/go-v2/developer-integration/sdks/ios/messaging)                                  | Sending events, handling requests, and response patterns              |
| [Capability Handling](/docs/go-v2/developer-integration/sdks/ios/capability-handling)              | Registering handlers, capability queries, and environment negotiation |
| [Security](/docs/go-v2/developer-integration/sdks/ios/security)                                    | Security model, content policies, and transport safety                |
| [Troubleshooting](/docs/go-v2/developer-integration/sdks/ios/troubleshooting)                      | Common issues, debugging techniques, and diagnostic tools             |
| [FAQ](/docs/go-v2/developer-integration/sdks/ios/faq)                                              | Frequently asked questions                                            |
| **Examples**                                                                                       |                                                                       |
| [Hello Journey](/docs/go-v2/developer-integration/sdks/ios/examples/hello-journey)                 | Minimal integration — load a journey and display it                   |
| [Two-Way Communication](/docs/go-v2/developer-integration/sdks/ios/examples/two-way-communication) | Send events and handle requests bidirectionally                       |
| [Advanced Integration](/docs/go-v2/developer-integration/sdks/ios/examples/advanced-integration)   | Custom config, lifecycle handling, error handling, capability checks  |

## License

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