> ## 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. # Capability Handling > Declaring, registering, and managing dynamic capability state on the host page. This guide explains how the GBGBridge Web SDK handles capabilities — the host-side features that web journeys can request. It covers the two-step declare-then-register pattern, the one-call alternative via `registerCustomCapability`, permission state, capability negotiation, and graceful-degradation patterns. ## What is a capability? A **capability** is a host-side feature the host page can fulfil on the journey's behalf. Examples: * `camera.document` — Document photo capture handled by the host page. * `camera.selfie` — Selfie / liveness capture handled by the host page. * `analytics.forward` — Forward analytics events from the journey to your telemetry pipeline. Capability IDs are dot-separated string keys. Standard IDs are exported as constants in `CAPABILITY_IDS` — use them to avoid typos: ```typescript theme={null} import { CAPABILITY_IDS } from "@gbg/go-bridge-web"; // CAPABILITY_IDS.CAMERA_DOCUMENT === "camera.document" ``` ## Two ways to declare and register Unlike iOS / Android — which use typed slots that combine declaration and handler registration in a single property assignment — the Web SDK keeps declaration and registration as separate concerns by default. There are two patterns: | Pattern | When to use | API | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **Two-step** | Capabilities you support at all times — declare them statically with the provider, register handlers near where the relevant UI lives | `capabilities` prop on `BridgeHostProvider` + `useBridgeCapability(...)` | | **One-call** | Capabilities you add dynamically at runtime, or capabilities tied to a single coordinator object | `host.registerCustomCapability(id, version, handler)` | Both can be used together. `registerCustomCapability` entries are merged with the constructor's `capabilities` map when building `capability.query` responses. ## Two-step: declare via prop, register via hook This is the default React pattern. The provider's `capabilities` prop declares what the host supports; `useBridgeCapability` attaches the handler that actually fulfils requests. ### Declaring capabilities Pass a `CapabilityMap` to the provider: ```tsx theme={null} import { BridgeHostProvider } from "@gbg/go-bridge-web-react"; import { CAPABILITY_IDS } from "@gbg/go-bridge-web"; {/* ... */} ``` Each `CapabilityInfo` entry can include: | Field | Type | Description | | ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------ | | `supported` | `boolean` | Whether the host can fulfil this capability. | | `version` | `string` | Optional version. Emitted as `null` in query responses when unset. | | `constraints` | `Record` | Optional. E.g., `{ maxResolution: 4096, formats: ["jpeg", "png"] }`. | | `permissionState` | `string` | Optional. E.g., `"granted"`, `"prompt"`, `"denied"`. Surfaced to the journey in query responses. | ### Registering handlers Use `useBridgeCapability` inside any descendant of the provider: ```tsx theme={null} import { useBridgeCapability } from "@gbg/go-bridge-web-react"; function DocumentCaptureHandler() { useBridgeCapability("camera.document.capture", { handle: async (request, responder) => { const data = (request.payload as { data: Record }).data; const side = data.side as string; const image = await captureDocument(side); responder.success({ image }); }, }); return null; } ``` The hook wraps the handler in a stable proxy — inline `{ handle: ... }` objects do not re-register on every render. On unmount the hook unregisters only if its proxy is still the active handler. ### Capability ID vs. action ID ``` capability ID → appears in capabilities prop, capability.query response e.g. "camera.document" action ID → appears in useBridgeCapability(...), payload.action e.g. "camera.document.capture" ``` These are related but distinct strings. Declaring `camera.document` does not implicitly register a handler for `camera.document.capture`. You need both. ## One-call: registerCustomCapability For dynamic capabilities — added after mount, conditional on runtime state, or tied to a non-React coordinator — call `host.registerCustomCapability(id, version, handler)` directly. It declares the capability AND registers the handler in one step. ```tsx theme={null} import { useBridgeHost } from "@gbg/go-bridge-web-react"; import { useEffect } from "react"; function NFCSupport() { const host = useBridgeHost(); useEffect(() => { if (!host) return; if (!("NDEFReader" in window)) return; // browser doesn't support NFC host.registerCustomCapability("nfc.read", "1.0", { handle: async (_request, responder) => { try { const reader = new (window as any).NDEFReader(); const chipData = await reader.scan(); responder.success({ mrz: chipData.mrz }); } catch (err) { responder.error({ code: "INTERNAL_ERROR", message: String(err), recoverable: true, }); } }, }); }, [host]); return null; } ``` The capability appears in the next `capability.query` response. There is no API to explicitly remove a custom capability — once registered, it lives for the lifetime of the host instance. ### Capability collision rules When the same capability ID appears in both the constructor `capabilities` map AND a `registerCustomCapability` call, **the constructor wins**. The query handler builds responses by merging in this order: ``` constructorCapabilities ∪ (customCapabilities \ keys(constructorCapabilities)) ``` — i.e., custom entries fill in IDs that the constructor didn't declare, but never override one that did. This matches Android's "configuration is authoritative" pattern and lets you safely use `registerCustomCapability` for runtime additions without worrying about clobbering your declared baseline. The action-handler registration is separate: whoever called `registerHandler` (or `registerCustomCapability` with a handler) most recently for a given action ID wins. If you need to verify ownership before re-registering, use `host.getHandler(action)` to inspect the current registration. ## Handler lifecycle and exceptions Capability handlers have a single lifecycle hook — `handle(request, responder)` — but several distinct exit paths affect what the journey sees. ### Successful terminal response ```typescript theme={null} useBridgeCapability("camera.document.capture", { handle: async (_request, responder) => { const image = await captureDocument(); responder.success({ imageBase64: image, mimeType: "image/jpeg" }); }, }); ``` Terminal methods (`success`, `error`, `cancelled`, `unsupported`) flip the responder's internal `hasResponded` flag. Any subsequent terminal call on the same responder is silently a no-op — exactly-once delivery is enforced at the responder level. ### `acknowledge()` for long-running operations ```typescript theme={null} handle: async (_request, responder) => { responder.acknowledge(); const result = await reallyLongRunningCapture(); // 10+ seconds responder.success({ image: result }); } ``` `acknowledge()` does NOT flip `hasResponded` and is chainable (returns `this`). Use it for handlers that exceed the journey-side default timeout (\~30s). A second `acknowledge()` is also a no-op — gated by a separate `hasAcknowledged` flag so a buggy handler can't spam duplicate ack envelopes. ### Handler throws or rejects before responding If the handler throws synchronously or its returned Promise rejects, and the responder has not yet been called, the SDK auto-sends a `HANDLER_FAILURE` response and routes the error to `delegate.onError`: ```typescript theme={null} handle: async (_request, responder) => { await iThrowSometimes(); // throws → SDK responds with HANDLER_FAILURE responder.success({}); // never reached } ``` The auto-response payload: ```json theme={null} { "status": "error", "error": { "code": "HANDLER_FAILURE", "message": "...", "recoverable": false } } ``` Without this, the journey would sit waiting until its own request timeout (\~30s) — the user would see a spinner instead of an error. `HANDLER_FAILURE` is NOT a member of the `BridgeErrorCode` enum (it's a raw string emitted on the wire). Journey-side consumers that pipe `response.error.code` through `toBridgeErrorCode(...)` see `INTERNAL_ERROR` (the documented fallback). If you need to distinguish handler failures from genuine `INTERNAL_ERROR`, match against the raw `error.code` string before normalising. ### Handler throws AFTER responding If a handler calls `responder.success(...)` and THEN throws (e.g., from stray cleanup code), the SDK logs a `console.warn` and does NOT flip the wire response. The journey sees the successful response; only the host's `delegate.onError` is notified about the post-terminal throw. This preserves wire truthfulness. ### Cleanup on unmount `useBridgeCapability` registers on mount and unregisters on unmount, **only if its own proxy is still the active handler**. Two components racing for the same action don't accidentally remove each other's installations. For non-React hosts using `registerHandler` directly, you own the unregistration lifecycle. If a handler is mid-flight when the component unmounts (e.g., still awaiting a capture), the responder reference may outlive the component. Either capture the responder in a ref and call `responder.cancelled("...")` from an unmount effect, or let the handler complete with its existing reference — the SDK doesn't care, but the journey-side journey may time out if the responder never resolves. ## Permission state Browser-mediated permissions (camera, microphone, geolocation, etc.) are not automatically detected by the SDK — unlike iOS, which ships `CameraDetector`. Query the browser yourself via `navigator.permissions.query()` and pass the result through `CapabilityInfo.permissionState`. ```typescript theme={null} async function getCameraPermissionState(): Promise { if (!navigator.permissions) return "prompt"; // older browsers try { const status = await navigator.permissions.query({ name: "camera" as PermissionName }); return status.state; // "granted" | "denied" | "prompt" } catch { return "prompt"; } } ``` ### Surfacing it to the journey ```tsx theme={null} function JourneyView({ journeyUrl }: { journeyUrl: string }) { const [iframe, setIframe] = useState(null); const [permissionState, setPermissionState] = useState("prompt"); useEffect(() => { getCameraPermissionState().then(setPermissionState); }, []); return (