Capability Handling - GBG Documentation

This guide explains how GBGBridge handles capabilities — the native features that a host application can provide to web journeys. It covers typed capability slots (recommended), custom capability registration, the legacy configuration approach, capability negotiation, permission state, and graceful degradation patterns.

What is a Capability?

A capability is a native device feature that the host app can provide to the web journey. Examples include:

camera.document: Document photography
camera.selfie: Facial capture for liveness checks
document.nfc: Reading the chip in a passport

Capabilities are identified by string keys using dot-separated namespaces.

Three Ways to Declare Capabilities

GBGBridge provides three approaches, listed from most to least recommended:

Approach	Best For	Init Method
Typed slots	Document/selfie capture, passport chip reading	`init(hostVersion:)`
Custom capability	Biometrics, or any capability without a typed slot	`init(hostVersion:)` + `registerCustomCapability()`
Configuration-based	Full manual control	`init(configuration:)` + `register(handler:)`

All three can be used together. Typed slots take precedence over custom capabilities with the same ID.

Typed Capability Slots (Recommended)

Typed slots are the recommended way to declare capture capabilities. Setting a handler on a slot simultaneously declares support and provides the implementation.

Basic Setup

let host = BridgeHost(hostVersion: "1.0.0")

// Declare document capture support
host.documentCapture.handler = { [weak host] request in
    guard let host else { return .cancelled(reason: "Host deallocated") }
    return await host.documentCapture.awaitCompletion()
}

// Declare selfie capture support
host.selfieCapture.handler = { [weak host] request in
    guard let host else { return .cancelled(reason: "Host deallocated") }
    return await host.selfieCapture.awaitCompletion()
}

Available Slots

Property	Capability ID	Action ID
`host.documentCapture`	`camera.document`	`camera.document.capture`
`host.selfieCapture`	`camera.selfie`	`camera.selfie.capture`
`host.nfcRead`	`document.nfc`	`document.nfc.read`

The capture slots are covered below. host.nfcRead takes a different request and result type: see Passport Chip Reading.

Handler-as-Declaration

With typed slots, there is no separate “declaration” step. A slot’s isSupported property is computed as handler != nil && isEnabled. When the web journey sends a capability.query request, only slots with handlers appear as supported.

// Not supported — no handler set
host.documentCapture.isSupported  // false

// Supported — handler is set
host.documentCapture.handler = { request in ... }
host.documentCapture.isSupported  // true

// Temporarily disabled — handler set but isEnabled is false
host.documentCapture.isEnabled = false
host.documentCapture.isSupported  // false

Returning Results

Typed slot handlers return CaptureResult values. The SDK encodes them into the bridge protocol format automatically — no manual JSONValue dictionary construction needed.

// Document capture success
return .document(DocumentCaptureResult(
    imageData: imageData,
    width: 1920,
    height: 1080,
    mimeType: "image/jpeg"
))

// Selfie capture success
return .selfie(SelfieCaptureResult(
    previewImageData: previewData,
    width: 640,
    height: 480,
    encryptedBlob: encryptedData,
    unencryptedBlob: unencryptedData
))

// User cancelled
return .cancelled(reason: "User dismissed camera")

// Failure
return .failed(
    code: "CAMERA_DENIED",
    message: "Camera permission was denied",
    recoverable: true
)

SwiftUI Integration with awaitCompletion()

The awaitCompletion() / complete() pattern bridges async handlers with SwiftUI’s declarative presentation:

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

    var body: some View {
        BridgeWebView(url: journeyURL, host: host)
            .onChange(of: host.documentCapture.activeRequest?.correlationId) { _ in
                showDocumentCamera = host.documentCapture.activeRequest != nil
            }
            .fullScreenCover(isPresented: $showDocumentCamera, onDismiss: {
                // If dismissed without completing, cancel the request
                if host.documentCapture.activeRequest != nil {
                    host.documentCapture.complete(.cancelled(reason: "Dismissed"))
                }
            }) {
                DocumentCameraView { imageData, width, height in
                    host.documentCapture.complete(.document(
                        DocumentCaptureResult(
                            imageData: imageData,
                            width: width,
                            height: height
                        )
                    ))
                }
            }
            .onAppear { setupHandlers() }
    }

    private func setupHandlers() {
        host.documentCapture.handler = { [weak host] request in
            guard let host else { return .cancelled(reason: "Host deallocated") }
            return await host.documentCapture.awaitCompletion()
        }
    }
}

The flow is:

Web journey sends camera.document.capture request.
Handler runs, sets activeRequest, calls awaitCompletion() — suspends.
SwiftUI detects activeRequest change, presents camera fullScreenCover.
Camera completes, view calls host.documentCapture.complete(.document(...)).
Handler resumes with the result, SDK encodes and sends the response.
activeRequest resets to nil, cover dismisses.

Busy Rejection

If a request arrives while another is already active on the same slot, the SDK automatically responds with an error:

{
  "status": "error",
  "error": {
    "code": "BUSY",
    "message": "A camera.document capture request is already in progress",
    "recoverable": true
  }
}

Permission State

Each typed slot has a permissionState property. Populate it using CameraDetector so the web journey can check permissions before attempting capture:

let camera = CameraDetector.check()
host.documentCapture.permissionState = camera.permissionState
host.selfieCapture.permissionState = camera.permissionState

This information appears in the capability.query response:

{
  "camera.document": {
    "supported": true,
    "version": "1.0",
    "permissionState": "granted"
  }
}

Enable/Disable at Runtime

Toggle isEnabled to temporarily disable a slot without removing the handler:

// Disable selfie capture for this journey
host.selfieCapture.isEnabled = false

// Re-enable later
host.selfieCapture.isEnabled = true

When disabled, the slot reports isSupported = false in capability queries.

Passport Chip Reading

Passport chip reading needs GBGBridge 1.2.0 or later.

host.nfcRead is the typed slot for reading the chip in a passport. It advertises document.nfc and answers document.nfc.read.

Don’t register chip reading as a custom capability, and never as nfc.read. nfc.read is a different capability (reading NFC tags), and the web journey never sends chip reads to it.

What Your App Does and What the SDK Does

Your handler runs a chip reader and hands back what it read, as an NfcReadResult. The SDK does the rest:

Checks the request carries the document number, date of birth and date of expiry, and answers MISSING_MRZ_DATA if one is missing.
Answers BUSY while a read is running.
Answers UNSUPPORTED when there is no handler, isEnabled is false, or deviceCanRead returns false.
Refuses a read where the chip never opened (NFC_AUTH_FAILED), or where DG1 held no readable MRZ (NFC_MRZ_UNAVAILABLE).
Drops DG16 and builds the response the web journey expects.

Don’t build the chip response yourself. Return the files and checks your reader produced, and let the SDK shape them. The request arrives as an NfcReadRequest with documentNumber, dateOfBirth and dateOfExpiry. Dates are YYMMDD. Check digits are not sent: the reader derives them.

App Setup

Chip reading uses Core NFC, so your app needs:

The Near Field Communication Tag Reading capability in Signing & Capabilities. This adds the com.apple.developer.nfc.readersession.formats entitlement with the TAG format.
These Info.plist entries. Without the select identifier, iOS can’t select the passport application and the read fails.

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

A deviceCanRead check. The SDK doesn’t link Core NFC, so it can’t tell whether the device has an NFC reader. deviceCanRead defaults to false, which reports chip reading as unsupported. Set it:

import CoreNFC

host.nfcRead.deviceCanRead = { NFCTagReaderSession.readingAvailable }

NFCTagReaderSession.readingAvailable is false on iPads and the Simulator. To try the flow on the Simulator with a mock reader, set deviceCanRead to { true }.

Presenting the Reader

Use the same pattern as the capture slots: the handler waits on awaitCompletion(), your view shows the reader while activeRequest is set, and calls complete(_:) with the result.

import CoreNFC
import GBGBridge
import SwiftUI

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

    var body: some View {
        BridgeWebView(url: journeyURL, host: host)
            .onChange(of: host.nfcRead.activeRequest) { request in
                showChipReader = request != nil
            }
            .sheet(isPresented: $showChipReader, onDismiss: {
                // Answers the read as cancelled if the person closed the reader. Safe when idle.
                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
                    }
                }
            }
            .onAppear { setupChipReading() }
    }

    private func setupChipReading() {
        host.nfcRead.deviceCanRead = { NFCTagReaderSession.readingAvailable }
        host.nfcRead.handler = { [weak host] _ in
            await host?.nfcRead.awaitCompletion() ?? .cancelled(reason: "Host deallocated")
        }
    }
}

ChipReaderView is your own view that runs the reader. It hands back one of:

// The reader finished: every file and check it returned
.read(files: files, checks: checks)

// The person cancelled
.cancelled(reason: "User cancelled the chip read")

// The read failed
.failed(.nfcReadFailed, message: "The chip stopped responding")

If the reader completes before the handler reaches awaitCompletion(), the SDK keeps the result and returns it when the handler waits.

Using the SmartCapture Ozone Reader

GBG SmartCapture includes a passport chip reader, Ozone (OzoneNFC.xcframework), which you get from your GBG account representative alongside the camera frameworks. Its OzoneNFCViewController shows the reading screen. Build it from the request:

OzoneNFCViewController(
    documentKey: OzoneNFCDocumentKey(
        passportNumber: request.documentNumber,
        dateOfBirth: request.dateOfBirth,
        expiryDate: request.dateOfExpiry
    ),
    completion: { result in
        host.nfcRead.complete(nfcReadResult(result))
    }
)

Then map what it returns to an NfcReadResult: the files from getRawDataGroup(dgId:), and the checks from the BAC, PACE, chip authentication and active authentication statuses plus passportDataValid.

import GBGBridge
import OzoneNFC

func nfcReadResult(_ result: Result<OzoneNFCDocument, OzoneNFCError>) -> NfcReadResult {
    switch result {
    case .success(let document):
        let groups: [(OzoneNFCDataGroup, String)] = [
            (.COM, "COM"), (.SOD, "SOD"),
            (.DG1, "DG1"), (.DG2, "DG2"), (.DG3, "DG3"), (.DG4, "DG4"), (.DG5, "DG5"),
            (.DG6, "DG6"), (.DG7, "DG7"), (.DG8, "DG8"), (.DG9, "DG9"), (.DG10, "DG10"),
            (.DG11, "DG11"), (.DG12, "DG12"), (.DG13, "DG13"), (.DG14, "DG14"), (.DG15, "DG15"),
            (.DG16, "DG16"),  // the SDK drops DG16
        ]
        let files = groups.compactMap { group, name in
            document.getRawDataGroup(dgId: group).map { NfcReadFile(name: name, bytes: Data($0)) }
        }
        let checks = [
            NfcAuthCheck(type: .basicAccessControl, result: authResult(document.BACStatus)),
            NfcAuthCheck(type: .supplementalAccessControl, result: authResult(document.PACEStatus)),
            NfcAuthCheck(type: .chipAuthentication, result: authResult(document.chipAuthenticationStatus)),
            NfcAuthCheck(type: .activeAuthentication, result: authResult(document.activeAuthenticationStatus)),
            NfcAuthCheck(type: .passiveAuthentication, result: document.passportDataValid ? .success : .failure),
        ]
        return .read(files: files, checks: checks)
    case .failure(.userCancelled):
        return .cancelled(reason: "User cancelled the chip read")
    case .failure(.invalidNfcKeyFormatting):
        return .failed(.missingMrzData, message: "The document number or dates are not in a form the reader accepts")
    case .failure(let error):
        return .failed(.nfcReadFailed, message: error.localizedDescription)
    }
}

func authResult(_ status: AuthStatus) -> NfcAuthResult {
    switch status {
    case .success: return .success
    case .failure: return .failure
    default: return .skipped
    }
}

Error Codes

These are the codes the web journey can receive. The SDK sends most of them itself. Your result sends MISSING_MRZ_DATA or NFC_READ_FAILED through .failed(_:message:), and CANCELLED through .cancelled(reason:).

Code	Status	When
`UNSUPPORTED`	`unsupported`	No handler, `isEnabled` is `false`, or `deviceCanRead` returns `false`
`NFC_DISABLED`	`error`	NFC is turned off in system settings (Android only: iOS has no such setting)
`BUSY`	`error`	A read is already running
`MISSING_MRZ_DATA`	`error`	The document number or a date is missing, or not in a form the reader accepts
`NFC_AUTH_FAILED`	`error`	The chip didn’t open with the access key (neither BAC nor PACE succeeded)
`NFC_MRZ_UNAVAILABLE`	`error`	The chip was read but DG1 held no readable MRZ
`NFC_READ_FAILED`	`error`	Any other failed read
`CANCELLED`	`cancelled`	The person cancelled or dismissed the reader

UNSUPPORTED is a hard stop: chip reading has no web fallback, so the journey asks the person to use a different device.

Moving From a Custom Capability

An app that answers chip reads with registerCustomCapability("document.nfc", actionId: "document.nfc.read") keeps working while host.nfcRead.handler is nil. Once you set the slot’s handler, the slot answers instead, so remove the custom capability when you move.

Custom Capability Registration

For capabilities that don’t have a typed slot, for example, biometrics, use registerCustomCapability():

import LocalAuthentication

let host = BridgeHost(hostVersion: "1.0.0")

host.registerCustomCapability(
    "biometric.auth",
    version: "1.0",
    isSupported: { LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) }
) { request, responder in
    let context = LAContext()
    guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil) else {
        responder.respond(
            status: .unsupported,
            data: nil,
            error: BridgeErrorPayload(
                code: "UNSUPPORTED",
                message: "Biometric authentication is not available on this device",
                recoverable: false
            )
        )
        return
    }

    do {
        let passed = try await context.evaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            localizedReason: "Confirm it's you"
        )
        responder.respond(status: .success, data: ["authenticated": .bool(passed)], error: nil)
    } catch {
        responder.respond(
            status: .error,
            data: nil,
            error: BridgeErrorPayload(
                code: "BIOMETRIC_ERROR",
                message: error.localizedDescription,
                recoverable: true
            )
        )
    }
}

Custom capabilities appear in capability.query responses as supported unless you pass isSupported:. The SDK asks isSupported on every query, so pass it when the device may lack the hardware or the feature can be switched off. Requests still reach the handler either way, so the handler should answer unsupported itself when it can’t help. Pass actionId: when the request action differs from the capability ID. If a typed slot exists for the same ID, the typed slot takes precedence.

Configuration-Based Approach (Legacy)

The configuration-based approach gives you full manual control. Use it when you need explicit capability dictionaries with constraints.

let configuration = BridgeConfiguration(
    hostVersion: "1.0.0",
    capabilities: [
        "camera.document": BridgeCapabilityInfo(
            supported: true,
            version: "1.0",
            constraints: [
                "maxResolution": .number(4096),
                "formats": .array([.string("jpeg"), .string("png")])
            ],
            permissionState: "granted"
        ),
        "biometric.auth": BridgeCapabilityInfo(
            supported: true,
            version: "1.0"
        )
    ]
)

let host = BridgeHost(configuration: configuration)
host.register(handler: DocumentCaptureHandler())
host.register(handler: BiometricAuthHandler())

With this approach, you implement BridgeCapabilityHandler for each action:

public final class BiometricAuthHandler: BridgeCapabilityHandler, @unchecked Sendable {
    public let action = "biometric.auth"

    public func handle(request: BridgeMessage, responder: BridgeResponder) async {
        // Handle the request and call responder.respond(...)
    }
}

Handler Lifecycle

Registration — Call host.register(handler:) before the web journey sends requests.
Request routing — When a matching request arrives, handle(request:responder:) is called in an async task.
Response — Call responder.respond(...) exactly once with the result.
Unregistration — Call host.unregister(action:) to remove a handler.

Capability Negotiation

How It Works

The web journey sends a capability.query request. GBGBridge’s built-in CapabilityQueryHandler responds automatically. When using init(hostVersion:), the response is built dynamically from typed slots and custom capabilities. When using init(configuration:), it uses the static BridgeConfiguration dictionary.

Query Response

The web journey receives:

{
  "environment": "ios",
  "hostVersion": "1.0.0",
  "capabilities": {
    "camera.document": { "supported": true, "version": "1.0", "permissionState": "granted" },
    "camera.selfie": { "supported": true, "version": "1.0", "permissionState": "notDetermined" },
    "document.nfc": { "supported": true, "version": "1.0" }
  }
}

The permissionState field appears when the capability provides permission metadata (typed slots with permissionState set, or BridgeCapabilityInfo with permissionState non-nil).

Environment-Specific Behavior

The Problem

Not all environments support the same capabilities:

Capability	iOS Native	Web (iframe)	Android Native
Camera capture	Yes	Limited	Yes
Passport chip read	Yes (iPhone 7+)	No	Yes (devices with NFC)
Face ID / Touch ID	Yes	No	Fingerprint/Face Unlock

When a web journey includes a chip-reading step but the host can’t read chips, the journey needs to know before reaching that step.

Detecting Environment from the Web Journey

The capability.query response includes an environment field ("ios", "android", or "web" for iframe hosts). The web journey uses both the environment and the capability flags to make routing decisions.

Runtime Hardware Detection on iOS

Use CameraDetector for camera hardware and permission detection:

let camera = CameraDetector.check()
// camera.hardwareAvailable — whether camera hardware exists
// camera.permissionState — .granted, .denied, .notDetermined, .restricted

For passport chip reading, set deviceCanRead on the slot. It defaults to false, so the slot reports chip reading as unsupported until you set it:

import CoreNFC

host.nfcRead.deviceCanRead = { NFCTagReaderSession.readingAvailable }

Graceful Degradation Patterns

When a capability isn’t available, your integration has two main routes: fall back to a web-based equivalent, or check upfront and prevent the user from starting a journey that won’t complete. The patterns below show both.

Pattern 1: Fall Back to Web or Skip

The web journey checks capabilities and adapts its flow. If a web-based fallback exists for the capability, the journey uses it. If there is no web equivalent, the step is skipped entirely.

Journey: Document Capture -> Biometric Check -> Face Match -> Result

If camera.document is unsupported (web fallback exists):
Journey: Document Capture (web) -> Biometric Check -> Face Match -> Result

If biometric.auth is unsupported (no web fallback):
Journey: Document Capture -> Face Match -> Result (Biometric Check skipped)

Passport chip reading is the exception. A chip-reading step is not skipped: when document.nfc is unsupported, the journey asks the person to use a different device. The host app doesn’t need to do anything special — the web journey handles fallback and routing decisions based on the capability query response.

Pattern 2: Check Permissions Before Starting

With permission state in the capability query, the web journey can detect permission issues and prompt the user:

If camera.document.permissionState == "denied":
    Show "Please enable camera access in Settings" before starting capture

Pattern 3: Respond with Unsupported Status

If the web journey sends a request for a capability the host doesn’t support, typed slots automatically respond with .unsupported when no handler is set. For custom capabilities, respond explicitly:

responder.respond(
    status: .unsupported,
    data: nil,
    error: BridgeErrorPayload(
        code: "CAPABILITY_UNAVAILABLE",
        message: "Biometric authentication is not available on this device",
        recoverable: false
    )
)

Dynamic Capability Updates

With typed slots, capability state is inherently dynamic:

Set or clear handler to change support status.
Toggle isEnabled to temporarily disable a slot.
Update permissionState when permissions change (e.g., after returning from Settings).

The web journey should re-query capabilities after significant state changes (e.g., after the app returns from background) to pick up any changes.

Next Steps

Security Guide — Transport security and content policies
Messaging Guide — Request/response patterns
Troubleshooting Guide — Diagnosing capability-related issues

​What is a Capability?

​Three Ways to Declare Capabilities

​Typed Capability Slots (Recommended)

​Basic Setup

​Available Slots

​Handler-as-Declaration

​Returning Results

​SwiftUI Integration with awaitCompletion()

​Busy Rejection

​Permission State

​Enable/Disable at Runtime

​Passport Chip Reading

​What Your App Does and What the SDK Does

​App Setup

​Presenting the Reader

​Using the SmartCapture Ozone Reader

​Error Codes

​Moving From a Custom Capability

​Custom Capability Registration

​Configuration-Based Approach (Legacy)

​Handler Lifecycle

​Capability Negotiation

​How It Works

​Query Response

​Environment-Specific Behavior

​The Problem

​Detecting Environment from the Web Journey

​Runtime Hardware Detection on iOS

​Graceful Degradation Patterns

​Pattern 1: Fall Back to Web or Skip

​Pattern 2: Check Permissions Before Starting

​Pattern 3: Respond with Unsupported Status

​Dynamic Capability Updates

​Next Steps

What is a Capability?

Three Ways to Declare Capabilities

Typed Capability Slots (Recommended)

Basic Setup

Available Slots

Handler-as-Declaration

Returning Results

SwiftUI Integration with awaitCompletion()

Busy Rejection

Permission State

Enable/Disable at Runtime

Passport Chip Reading

What Your App Does and What the SDK Does

App Setup

Presenting the Reader

Using the SmartCapture Ozone Reader

Error Codes

Moving From a Custom Capability

Custom Capability Registration

Configuration-Based Approach (Legacy)

Handler Lifecycle

Capability Negotiation

How It Works

Query Response

Environment-Specific Behavior

The Problem

Detecting Environment from the Web Journey

Runtime Hardware Detection on iOS

Graceful Degradation Patterns

Pattern 1: Fall Back to Web or Skip

Pattern 2: Check Permissions Before Starting

Pattern 3: Respond with Unsupported Status

Dynamic Capability Updates

Next Steps