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

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:

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

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

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:

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

<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 format. If you see decode errors in lastError, verify that the web content is sending correctly structured JSON.

Next Steps

• Concepts — Understand the architecture and mental model
• Messaging Guide — Learn to send events and handle requests
• Capability Handling Guide — Register handlers for camera, NFC, and other capabilities
• API Reference — Detailed reference for every public symbol