Web Bridge SDK - GBG Documentation

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 and Android Bridge SDK — no postMessage plumbing on your side.

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.

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

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

npm install @gbg/go-bridge-web @gbg/go-bridge-web-react

Availability: these packages will publish to public npm via GGO-13991. The SDK source lives in the reference build under packages/ until the public package is available.

Reference app

The 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 and gbg-go-android-reference. Walkthrough lives in the Tutorial.

Documentation map

Document	Description
Tutorial	Build a complete web identity verification app from scratch
Getting Started	Step-by-step installation, setup, and first integration
Concepts	Architecture, mental model, terminology, and design rationale
API Reference	Complete reference for every public type, method, and property
Guides
Embedding	Embedding the iframe in React and framework-agnostic apps
Messaging	Sending events, handling requests, and response patterns
Capability Handling	Registering handlers, capability queries, and environment negotiation
Capture Screens	Building capture UI in the host page when journey delegates capture
Security	Security model, CSP, origin allowlist, and transport safety
Troubleshooting	Common issues, debugging techniques, and diagnostic tools
FAQ	Frequently asked questions
Examples
Hello Journey	Minimal integration — load a journey and display it
Two-Way Communication	Send events and handle requests bidirectionally
Advanced Integration	Custom config, lifecycle handling, error handling, capability checks

License

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

​What GBGBridge enables

​Architecture at a glance

​Quick start

​Requirements

​Installation

​Reference app

​Documentation map

​License

What GBGBridge enables

Architecture at a glance

Quick start

Requirements

Installation

Reference app

Documentation map

License