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

# Getting Started

> Install GBGBridge and build your first integration in minutes.

This guide walks you through adding GBGBridge to your iOS project, configuring it, and loading your first web-based identity journey.

## Requirements

| Requirement  | Minimum | Notes                                                      |
| ------------ | ------- | ---------------------------------------------------------- |
| iOS          | 15.0    | Required for Swift concurrency and modern SwiftUI features |
| Swift        | 5.9+    | Binary module stability ensures forward compatibility      |
| Xcode        | 15.0+   | Matches Swift 5.9 toolchain                                |
| Architecture | arm64   | Device and Simulator (arm64 + x86\_64) slices included     |

GBGBridge has **zero external dependencies**. It uses only system frameworks: Foundation, WebKit, Combine, SwiftUI, and AVFoundation (for camera detection).

## Installation

GBGBridge is distributed as a Swift Package. Use Swift Package Manager for most projects, or grab the XCFramework manually if you don't use SPM.

### Swift Package Manager (recommended)

1. In Xcode, go to **File** > **Add Package Dependencies...**
2. Enter the GBGBridge package URL:
   ```
   https://github.com/gbgplc/gbg-go-ios-sdk
   ```
3. Select the version rule, for example, **Up to Next Major Version** from `1.0.0`.
4. Click **Add Package**.
5. Ensure **GBGBridge** is added to your app target.

### Manual XCFramework

If you prefer manual integration:

1. Download the `GBGBridge.xcframework.zip` from the [latest release](https://github.com/gbgplc/gbg-go-ios-sdk/releases/latest).
2. Unzip the archive.
3. Drag `GBGBridge.xcframework` into your Xcode project.
4. In your target's **General → Frameworks, Libraries, and Embedded Content**, ensure GBGBridge is set to **Embed & Sign**.

## Minimal Integration

### 1. Import the Framework

```swift theme={null}
import GBGBridge
```

### 2. Initialize the Bridge Host

The `BridgeHost` manages message routing between the WebView and your native code. The simplest way to create one is with a host version string:

```swift theme={null}
@StateObject private var host = BridgeHost(hostVersion: "1.0.0")
```

### 3. Declare Capabilities via Typed Slots

`BridgeHost` exposes typed capability slots for well-known capture operations. Setting a handler on a slot declares support — no separate configuration step needed:

```swift theme={null}
// Declare document capture support by setting a handler
host.documentCapture.handler = { request in
    // Your capture logic here — return a CaptureResult
    return .cancelled(reason: "Not yet implemented")
}

// Optionally detect and report camera permission state
let camera = CameraDetector.check()
host.documentCapture.permissionState = camera.permissionState
```

### 4. Display the Journey

Use `BridgeWebView` to load the web journey. It handles WebView creation, bootstrap script injection, and message handler registration automatically.

```swift theme={null}
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 {
            host.documentCapture.handler = { request in
                return await host.documentCapture.awaitCompletion()
            }
        }
    }
}
```

### 5. Run Your App

Build and run. The web journey loads inside the native WebView. When the journey sends a `capability.query` request, GBGBridge automatically responds with the capabilities derived from your typed slots — including which are supported and their permission state.

### Alternative: Configuration-Based Initialization

If you need explicit control over the capability dictionary (e.g., for non-camera capabilities or constraints), use the configuration-based initializer:

```swift theme={null}
let configuration = BridgeConfiguration(
    hostVersion: "1.0.0",
    capabilities: [
        "camera.capture": BridgeCapabilityInfo(supported: true, version: "1.0"),
        "nfc.read": BridgeCapabilityInfo(supported: false)
    ]
)

@StateObject private var host = BridgeHost(configuration: configuration)
```

Both initialization paths support `register(handler:)` for custom `BridgeCapabilityHandler` implementations. See the [Capability Handling Guide](/docs/go-v2/developer-integration/sdks/ios/capability-handling) for details.

## What Happens Under the Hood

When `BridgeWebView` creates the WebView, several things happen automatically:

1. **Bootstrap script injection**: A JavaScript snippet is injected at document start that initializes `window.GBGBridge` with a `receive()` function. This ensures the bridge is available before the web content loads.
2. **Message handler registration**: The `BridgeHost` registers itself as the handler for the `gbgBridge` script message channel.
3. **Capability query handler**: A built-in handler for the `capability.query` action is registered. When using `init(hostVersion:)`, the query response is built dynamically from typed slots and custom capabilities, including permission state metadata.

## Required App Configuration

GBGBridge itself does not require any `Info.plist` entries or entitlements. However, depending on the capabilities you expose, your host app will need appropriate permissions:

| Capability    | Info.plist Key                   | Example Value                                             |
| ------------- | -------------------------------- | --------------------------------------------------------- |
| Camera        | `NSCameraUsageDescription`       | "Camera access is required for document capture."         |
| NFC           | `NSNFCReaderUsageDescription`    | "NFC is used to read identity document chips."            |
| Photo Library | `NSPhotoLibraryUsageDescription` | "Photo library access is used to select document images." |

For NFC specifically, you must also:

* Add the **Near Field Communication Tag Reading** capability in your target's Signing & Capabilities.
* Include `com.apple.developer.nfc.readersession.formats` in your entitlements file.

## Common Integration Pitfalls

A handful of issues catch most teams when first wiring up the bridge — wrong WebView setup, missing capability declarations, ATS rejecting non-HTTPS dev URLs, and malformed messages on the web side. The notes below explain what to check.

### WebView not receiving messages

Ensure you are using `BridgeWebView` or `BridgeWebViewConfigurator.configure(_:host:)` — not a plain `WKWebView`. The bootstrap script and message handler must be set up before the page loads.

### Capability query returns empty

If using `init(hostVersion:)`: check that you set a `handler` on at least one typed slot, or registered a custom capability via `registerCustomCapability()`. If using `init(configuration:)`: check that you passed capabilities in your `BridgeConfiguration`.

### App Transport Security errors

If your journey URL uses a local development server (e.g., `http://localhost`), add the following to your Info.plist:

```xml theme={null}
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>
```

For production, always use HTTPS. Do not disable App Transport Security globally.

### Messages not decoding

GBGBridge expects messages in the [Bridge Message Protocol](/docs/go-v2/developer-integration/sdks/ios/concepts#message-protocol) format. If you see decode errors in `lastError`, verify that the web content is sending correctly structured JSON.

## Next Steps

* [Concepts](/docs/go-v2/developer-integration/sdks/ios/concepts) — Understand the architecture and mental model
* [Messaging Guide](/docs/go-v2/developer-integration/sdks/ios/messaging) — Learn to send events and handle requests
* [Capability Handling Guide](/docs/go-v2/developer-integration/sdks/ios/capability-handling) — Register handlers for camera, NFC, and other capabilities
* [API Reference](/docs/go-v2/developer-integration/sdks/ios/api-reference) — Detailed reference for every public symbol