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

# Web Bridge SDK

> Embed GBG GO identity verification journeys in your web app using the GBGBridge SDK.

GBGBridge is a lightweight TypeScript SDK for embedding web-based identity journeys in your own web pages. It provides a type-safe messaging protocol so journey content loaded inside an `<iframe>` can request host capabilities through a structured event bus, with the same wire protocol as the [iOS Bridge SDK](/docs/go-v2/developer-integration/sdks/ios-sdk) and [Android Bridge SDK](/docs/go-v2/developer-integration/sdks/android-sdk) — no `postMessage` plumbing on your side.

<Note>
  **Not the SDK you're looking for?** This is the host-page SDK — for pages that embed a GBG journey iframe. If you're building the journey content that runs inside the iframe, see the [TypeScript Bridge SDK](/docs/go-v2/developer-integration/sdks/typescript-sdk).
</Note>

## What GBGBridge enables

* **Host capability access from embedded journeys**: Journey content running inside an `<iframe>` can request host-side features through a standardized message protocol.
* **Standard capability identifiers**: Built-in constants (`camera.document`, `camera.selfie`, etc.) define common capabilities so host and journey speak the same action names. Capability query responses are built automatically from your declarations.
* **Bidirectional messaging**: Both the host page and the embedded journey can send and receive structured messages, enabling real-time coordination.
* **Capability negotiation with permission state**: The web journey can query which host capabilities are available — including camera permission status — before attempting to use them, enabling graceful degradation across environments.
* **Drop-in React integration**: A separate `@gbg/go-bridge-web-react` package exposes a `BridgeHostProvider` and hooks for declarative integration with React apps. The core `@gbg/go-bridge-web` package is framework-agnostic and works with React, Vue, Angular, Svelte, or vanilla JavaScript.
* **Extensible handler architecture**: Register custom capability handlers to fulfil any request type the web journey might send — extending beyond the standard capability identifiers when needed.

## Architecture at a glance

GBGBridge sits between your web page and the embedded journey, routing structured messages in both directions over the browser's `postMessage` channel:

```mermaid theme={null}
graph TB
    subgraph Host["Host Page (Your Web App)"]
        BH[BridgeHost<br/>message router]
        CH[Capability Handlers<br/>camera · custom]
        IF[iframe element]
        BH <--> CH
        BH <--> IF
    end
    Web["Web Journey (JavaScript)"]
    IF -- "iframe.contentWindow.postMessage" --> Web
    Web -- "window.postMessage<br/>(origin-validated)" --> IF
```

The embedded journey sends structured JSON messages to the host page via `window.postMessage()`. The `BridgeHost` validates the source iframe and origin allowlist, decodes each message, routes requests to registered capability handlers, and sends responses back via `iframe.contentWindow.postMessage()`.

## Quick start

The minimum integration is a `BridgeHostProvider` with the capabilities you support declared, an `<iframe>` pointed at your journey URL, and a handler registered for the document-capture action:

```tsx theme={null}
import { BridgeHostProvider, useBridgeCapability } from "@gbg/go-bridge-web-react";
import { useState } from "react";

export function JourneyView({ journeyUrl }: { journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
  const allowedOrigins = [new URL(journeyUrl).origin];

  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={allowedOrigins}
      hostVersion="1.0.0"
      capabilities={{
        "camera.document": { supported: true, version: "1.0" },
      }}
    >
      <DocumentCaptureHandler />
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

function DocumentCaptureHandler() {
  useBridgeCapability("camera.document.capture", {
    handle: async (request, responder) => {
      // Present your camera UI and respond with the captured image
      const image = await captureDocument();
      responder.success({ image });
    },
  });
  return null;
}
```

The `BridgeHostProvider` builds the underlying `BridgeHost` once the iframe element is attached, sets up the `postMessage` listener, validates origins, and routes messages. Registering a handler via `useBridgeCapability` attaches it to an action — the journey can then call into it. Declaring the capability via the `capabilities` prop tells the journey it's supported, so it knows to invoke the handler rather than fall back. **Both are required.**

The core `@gbg/go-bridge-web` package is framework-agnostic — see [Getting Started](/docs/go-v2/developer-integration/sdks/web/getting-started) for vanilla JavaScript, Vue, Angular, or Svelte setup.

## Requirements

| Requirement                  | Minimum                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| Browsers                     | ES2020 / modern evergreen browsers                                                 |
| Node.js (build)              | 18+                                                                                |
| TypeScript                   | 5.x (types ship with the package)                                                  |
| React (for `-react` package) | 19.x                                                                               |
| Distribution                 | npm — ESM with `.d.ts` declarations                                                |
| Dependencies                 | None (zero runtime dependencies; React is a peer dependency for the React package) |

## Installation

```bash theme={null}
npm install @gbg/go-bridge-web @gbg/go-bridge-web-react
```

<Note>
  **Availability:** these packages will publish to public npm via [GGO-13991](https://gbg.atlassian.net/browse/GGO-13991). The SDK source lives in the [reference build](https://github.com/gbgplc/gbg-go-web-reference) under `packages/` until the public package is available.
</Note>

## Reference app

The [GBG Go Web Reference](https://github.com/gbgplc/gbg-go-web-reference) is a complete sample app showing this SDK against the real GBG GO backend, mirroring the structure of [gbg-go-ios-reference](https://github.com/gbgplc/gbg-go-ios-reference) and [gbg-go-android-reference](https://github.com/gbgplc/gbg-go-android-reference). Walkthrough lives in the [Tutorial](/docs/go-v2/developer-integration/sdks/web/tutorial).

## Documentation map

| Document                                                                                           | Description                                                           |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Tutorial](/docs/go-v2/developer-integration/sdks/web/tutorial)                                    | Build a complete web identity verification app from scratch           |
| [Getting Started](/docs/go-v2/developer-integration/sdks/web/getting-started)                      | Step-by-step installation, setup, and first integration               |
| [Concepts](/docs/go-v2/developer-integration/sdks/web/concepts)                                    | Architecture, mental model, terminology, and design rationale         |
| [API Reference](/docs/go-v2/developer-integration/sdks/web/api-reference)                          | Complete reference for every public type, method, and property        |
| **Guides**                                                                                         |                                                                       |
| [Embedding](/docs/go-v2/developer-integration/sdks/web/embedding)                                  | Embedding the iframe in React and framework-agnostic apps             |
| [Messaging](/docs/go-v2/developer-integration/sdks/web/messaging)                                  | Sending events, handling requests, and response patterns              |
| [Capability Handling](/docs/go-v2/developer-integration/sdks/web/capability-handling)              | Registering handlers, capability queries, and environment negotiation |
| [Capture Screens](/docs/go-v2/developer-integration/sdks/web/capture-screens)                      | Building capture UI in the host page when journey delegates capture   |
| [Security](/docs/go-v2/developer-integration/sdks/web/security)                                    | Security model, CSP, origin allowlist, and transport safety           |
| [Troubleshooting](/docs/go-v2/developer-integration/sdks/web/troubleshooting)                      | Common issues, debugging techniques, and diagnostic tools             |
| [FAQ](/docs/go-v2/developer-integration/sdks/web/faq)                                              | Frequently asked questions                                            |
| **Examples**                                                                                       |                                                                       |
| [Hello Journey](/docs/go-v2/developer-integration/sdks/web/examples/hello-journey)                 | Minimal integration — load a journey and display it                   |
| [Two-Way Communication](/docs/go-v2/developer-integration/sdks/web/examples/two-way-communication) | Send events and handle requests bidirectionally                       |
| [Advanced Integration](/docs/go-v2/developer-integration/sdks/web/examples/advanced-integration)   | Custom config, lifecycle handling, error handling, capability checks  |

## License

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