@gbg/go-bridge-web-react

React bindings for @gbg/go-bridge-web — a Provider and hooks for embedding GBG GO identity verification journeys in a React app via iframe.

The core package's README covers prerequisites (you need a GBG GO agreement and a configured journey), the messaging protocol, capability discovery, and the security model; this package layers React lifecycle management on top.

Installation

Requires React 19 (peerDependencies: react 19.x). On React 18 or earlier, use the framework-agnostic core package directly instead.

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

Quick start

import { useState } from 'react';
import type { CapabilityMap } from '@gbg/go-bridge-web';
import {
  BridgeHostProvider,
  useBridgeCapability,
  useBridgeHostError,
  useBridgeHostEvent,
} from '@gbg/go-bridge-web-react';

const CAPABILITIES: CapabilityMap = {
  'analytics.forward': { supported: true, version: '1.0' },
};

function JourneyEmbed({ journeyUrl }: { journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);

  return (
    <BridgeHostProvider
      key={journeyUrl}
      iframe={iframe}
      allowedOrigins={[new URL(journeyUrl).origin]}
      hostVersion="my-app-1.0.0"
      capabilities={CAPABILITIES}
    >
      <iframe
        ref={setIframe}
        src={journeyUrl}
        title="Identity verification"
        sandbox="allow-scripts allow-same-origin allow-forms"
        allow="camera"
        style={{ width: '100%', height: 480, border: 0 }}
      />
      <JourneyListeners />
    </BridgeHostProvider>
  );
}

function JourneyListeners() {
  // Handle requests from the journey.
  useBridgeCapability('analytics.forward', {
    handle: (request, responder) => {
      const { data } = request.payload as { data: Record<string, unknown> };
      myTelemetry.track(data); // your analytics client — not part of the SDK
      responder.success({});
    },
  });

  // Observe fire-and-forget events from the journey.
  useBridgeHostEvent('journey.completed', (data) => {
    console.log('journey completed', data);
  });

  useBridgeHostError((err) => {
    console.error('bridge error', err);
  });

  return null;
}

API

<BridgeHostProvider>

Creates a BridgeHost once the iframe prop becomes non-null and detaches it automatically on unmount or iframe change — you never call detach() yourself.

| Prop | Type | Notes | | --- | --- | --- | | iframe | HTMLIFrameElement \| null | Pass null until the iframe has mounted (e.g. via a ref callback). | | allowedOrigins | string[] | Required. Exact origins the journey is served from. | | hostVersion | string? | Reported to the journey in capability discovery. | | capabilities | CapabilityMap? | What your page supports. | | delegate | BridgeHostDelegate? | Raw message/error observability hooks. |

allowedOrigins, hostVersion, and capabilities are read when the host is created (when iframe transitions to non-null, or changes to a new element) and are not applied on later renders; delegate is read live, so swapping it takes effect immediately. To apply changed configuration, remount the Provider — keying it on the config, as with key={journeyUrl} above, is the simplest way.

useBridgeHost(): BridgeHost | null

Returns the live BridgeHost, or null before the iframe mounts. Use it for imperative calls in response to something happening:

const host = useBridgeHost();
return (
  <button
    onClick={() => host?.sendEvent('host.locale.update', { locale: 'en-GB' })}
  >
    Switch locale
  </button>
);

(As the core README notes, sends are not queued — only send once the journey is running.)

useBridgeCapability(action, handler): void

Registers a request handler for the lifetime of the calling component. The hook keeps the registration stable across renders, so an inline { handle: ... } literal is fine.

Don't mount two live handlers for the same action: the newest registration replaces the older one. Unmounting the replaced component is safe (it won't remove the newer registration), but the replaced handler is never reinstated — when the newer component unmounts, the action is left with no handler at all. One component per action.

useBridgeHostEvent(action, listener): void

Subscribes to fire-and-forget events from the journey (e.g. the journey.* lifecycle actions — see BridgeActions in the core package). The subscription is renewed whenever the listener's identity changes; memoize it with useCallback if your component re-renders frequently.

useBridgeHostError(listener): void

Subscribes to bridge errors: capability-handler throws (before a response has been sent), delegate throws, and postMessage exceptions. Sends the SDK drops for other reasons (no iframe src yet, origin not allowlisted) surface as console warnings, not errors, and sends made through a stale host reference after the Provider has detached it (unmount or iframe change) are dropped silently — see the core README. Memoize the listener with useCallback.

License

MIT © GBG Group plc