Embedding - GBG Documentation

This guide covers how to embed the bridge-connected iframe in your web application — including React, vanilla JavaScript / Vue / Angular / Svelte, server-rendered frameworks, and multi-iframe pages.

React integration

For React apps, BridgeHostProvider is the recommended path: wrap your iframe-rendering subtree, track the iframe element in state, and use hooks to interact with the bridge.

Using BridgeHostProvider

import { BridgeHostProvider, useBridgeCapability } from "@gbg/go-bridge-web-react";
import { useState } from "react";

export function JourneyScreen({ 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) => {
      const image = await captureDocument();
      responder.success({ image });
    },
  });
  return null;
}

The provider builds the underlying BridgeHost once iframe transitions from null to a real element. Children using the hooks see host come online at that point.

Reading bridge state in components

useBridgeHost() returns the current BridgeHost, or null while the iframe isn’t attached. Use it to read observable state and call imperative methods.

import { useBridgeHost } from "@gbg/go-bridge-web-react";

function MessageCountBadge() {
  const host = useBridgeHost();
  const count = host?.receivedMessages.length ?? 0;
  return <span className="badge">{count}</span>;
}

host.receivedMessages and host.pendingRequests are arrays, not observables. They mutate in place as messages arrive — React will not re-render the badge component unless something else triggers a render. For reactive UI, subscribe to events via useBridgeHostEvent or to errors via useBridgeHostError, and lift state to your own components.

Listening for events

Subscribe to specific event actions emitted by the journey using useBridgeHostEvent:

import { useBridgeHostEvent } from "@gbg/go-bridge-web-react";
import { useNavigate } from "react-router-dom";

function JourneyCompletionRouter() {
  const navigate = useNavigate();

  useBridgeHostEvent("journey.completed", (data) => {
    navigate(`/success?journey=${data.journeyId}`);
  });

  useBridgeHostEvent("journey.failed", (data) => {
    navigate(`/failure?reason=${data.reason}`);
  });

  return null;
}

The hook subscribes on mount and unsubscribes on unmount. Stable listener identities (via useCallback) prevent re-subscription on every render.

Surfacing errors

Subscribe to internal SDK errors with useBridgeHostError and lift to React state if you need to render them:

import { useBridgeHostError } from "@gbg/go-bridge-web-react";
import { useState } from "react";

function ErrorBanner() {
  const [error, setError] = useState<Error | null>(null);
  useBridgeHostError(setError);

  if (!error) return null;
  return <div className="error-banner">{error.message}</div>;
}

Dynamic journey URLs

Two patterns for changing journey URLs. Pattern A — Update iframe.src (preserves the BridgeHost):

function DynamicJourney() {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
  const [journeyUrl, setJourneyUrl] = useState("https://journey.example.com/step1");

  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={["https://journey.example.com"]}
      hostVersion="1.0.0"
    >
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
      <button onClick={() => setJourneyUrl("https://journey.example.com/step2")}>
        Next step
      </button>
    </BridgeHostProvider>
  );
}

The host’s allowedOrigins snapshot still applies — both URLs must share an origin already in the allowlist. Pattern B — Remount the provider (rebuilds the host with fresh config):

function MultiOriginJourney() {
  const [origin, setOrigin] = useState("https://journey-eu.example.com");
  return (
    <BridgeHostProvider
      key={origin}
      iframe={iframe}
      allowedOrigins={[origin]}
      hostVersion="1.0.0"
    >
      {/* ... */}
    </BridgeHostProvider>
  );
}

Changing key discards the existing host (calls detach) and rebuilds with the new config. Use this when allowedOrigins, hostVersion, or capabilities need to change at runtime.

Multiple iframes on one page

Each BridgeHostProvider is independent and owns its own BridgeHost. Use this pattern when you have two side-by-side journeys, or when you split capture flows into separate iframes.

function SplitView() {
  const [iframeA, setIframeA] = useState<HTMLIFrameElement | null>(null);
  const [iframeB, setIframeB] = useState<HTMLIFrameElement | null>(null);

  return (
    <div className="split">
      <BridgeHostProvider iframe={iframeA} allowedOrigins={[...]} hostVersion="1.0.0">
        <DocumentCaptureHandler />
        <iframe ref={setIframeA} src={urlA} allow="camera" />
      </BridgeHostProvider>
      <BridgeHostProvider iframe={iframeB} allowedOrigins={[...]} hostVersion="1.0.0">
        <SelfieCaptureHandler />
        <iframe ref={setIframeB} src={urlB} allow="camera" />
      </BridgeHostProvider>
    </div>
  );
}

The two hosts are isolated — events and capabilities don’t cross between them.

Framework-agnostic integration

If you’re not using React, instantiate BridgeHost directly from the core @gbg/go-bridge-web package.

Vanilla JavaScript

import { BridgeHost } from "@gbg/go-bridge-web";

const iframe = document.getElementById("journey-frame") as HTMLIFrameElement;
const journeyUrl = "https://journey.example.com";
iframe.src = journeyUrl;

const host = new BridgeHost({
  iframe,
  allowedOrigins: [new URL(journeyUrl).origin],
  hostVersion: "1.0.0",
  capabilities: {
    "camera.document": { supported: true, version: "1.0" },
  },
});

host.registerHandler("camera.document.capture", {
  handle: async (request, responder) => {
    const image = await captureDocument();
    responder.success({ image });
  },
});

// When the journey screen is removed from the page:
function teardown() {
  host.detach();
}

With direct usage you own the lifecycle. Call host.detach() when the iframe is removed or the screen unmounts to release the window message listener.

Vue 3 (Composition API)

<script setup lang="ts">
import { BridgeHost } from "@gbg/go-bridge-web";
import { ref, onMounted, onUnmounted } from "vue";

const props = defineProps<{ journeyUrl: string }>();
const iframeRef = ref<HTMLIFrameElement | null>(null);
let host: BridgeHost | null = null;

onMounted(() => {
  if (!iframeRef.value) return;
  host = new BridgeHost({
    iframe: iframeRef.value,
    allowedOrigins: [new URL(props.journeyUrl).origin],
    hostVersion: "1.0.0",
    capabilities: {
      "camera.document": { supported: true, version: "1.0" },
    },
  });
  host.registerHandler("camera.document.capture", {
    handle: async (_request, responder) => {
      const image = await captureDocument();
      responder.success({ image });
    },
  });
});

onUnmounted(() => {
  host?.detach();
});
</script>

<template>
  <iframe ref="iframeRef" :src="props.journeyUrl" allow="camera" />
</template>

Angular

import { Component, ElementRef, ViewChild, AfterViewInit, OnDestroy, Input } from "@angular/core";
import { BridgeHost } from "@gbg/go-bridge-web";

@Component({
  selector: "app-journey",
  template: `<iframe #journey [src]="journeyUrl" allow="camera"></iframe>`,
})
export class JourneyComponent implements AfterViewInit, OnDestroy {
  @Input() journeyUrl!: string;
  @ViewChild("journey") iframeRef!: ElementRef<HTMLIFrameElement>;
  private host: BridgeHost | null = null;

  ngAfterViewInit() {
    this.host = new BridgeHost({
      iframe: this.iframeRef.nativeElement,
      allowedOrigins: [new URL(this.journeyUrl).origin],
      hostVersion: "1.0.0",
      capabilities: { "camera.document": { supported: true, version: "1.0" } },
    });
    this.host.registerHandler("camera.document.capture", {
      handle: async (_request, responder) => {
        const image = await captureDocument();
        responder.success({ image });
      },
    });
  }

  ngOnDestroy() {
    this.host?.detach();
  }
}

Svelte

<script lang="ts">
  import { BridgeHost } from "@gbg/go-bridge-web";
  import { onMount, onDestroy } from "svelte";

  export let journeyUrl: string;
  let iframeEl: HTMLIFrameElement;
  let host: BridgeHost | null = null;

  onMount(() => {
    host = new BridgeHost({
      iframe: iframeEl,
      allowedOrigins: [new URL(journeyUrl).origin],
      hostVersion: "1.0.0",
      capabilities: { "camera.document": { supported: true, version: "1.0" } },
    });
    host.registerHandler("camera.document.capture", {
      handle: async (_request, responder) => {
        const image = await captureDocument();
        responder.success({ image });
      },
    });
  });

  onDestroy(() => host?.detach());
</script>

<iframe bind:this={iframeEl} src={journeyUrl} allow="camera" />

Server-side rendering (Next.js, Remix, SvelteKit)

BridgeHost requires window, MessageEvent, and DOM access — none of which exist on the server. The SDK must run client-side only.

Next.js (App Router)

Mark the journey component with "use client" and let it render only on the client:

// app/journey/JourneyClient.tsx
"use client";

import { BridgeHostProvider } from "@gbg/go-bridge-web-react";
import { useState } from "react";

export function JourneyClient({ journeyUrl }: { journeyUrl: string }) {
  const [iframe, setIframe] = useState<HTMLIFrameElement | null>(null);
  return (
    <BridgeHostProvider
      iframe={iframe}
      allowedOrigins={[new URL(journeyUrl).origin]}
      hostVersion="1.0.0"
      capabilities={{ "camera.document": { supported: true, version: "1.0" } }}
    >
      <iframe ref={setIframe} src={journeyUrl} allow="camera" />
    </BridgeHostProvider>
  );
}

// app/journey/page.tsx (server component)
import { JourneyClient } from "./JourneyClient";

export default async function JourneyPage() {
  const journeyUrl = await getJourneyUrl(); // server-side: fetch tokenized URL
  return <JourneyClient journeyUrl={journeyUrl} />;
}

The server component handles the token exchange (calling @gbg/go-core server-side), and only the journey URL crosses to the client.

Next.js (Pages Router) and other SSR frameworks

If you can’t mark a component as client-only, gate the bridge setup on a useEffect so it never runs during server render:

import { useEffect, useState } from "react";

export function JourneyView({ journeyUrl }: { journeyUrl: string }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (!mounted) return null; // skip SSR

  return <ActualJourney journeyUrl={journeyUrl} />;
}

For Vue / Nuxt / SvelteKit, use the equivalent client-only gate (<ClientOnly> in Nuxt, onMount in SvelteKit).

Lifecycle considerations

BridgeHostProvider handles most of this for you in React. For non-React hosts, you own the lifecycle. Either way, these rules apply.

Set up handlers before the journey requests them

If a request arrives before its handler is registered, it goes to pendingRequests. The journey will be left waiting (or time out) until you respond manually via host.respond(...). Register handlers before the iframe loads — in React, mount the handler components inside the provider; in vanilla JS, call registerHandler immediately after new BridgeHost(...).

Detach when the iframe is removed

Call host.detach() (or unmount the provider) when the iframe goes away. Failing to detach leaves the window message listener attached and the BridgeHost instance reachable from a closure — a small leak that compounds across navigation.

Config snapshot at attach time

BridgeHostProvider snapshots allowedOrigins, hostVersion, and capabilities when the underlying host is built. To apply runtime changes:

Use a key-based remount to discard and rebuild.
For capabilities specifically, use host.registerCustomCapability(id, version, handler) via useBridgeHost() — it adds to the effective capability map at runtime without rebuilding the host.

iframe.src and outbound message timing

HostIframeChannel resolves targetOrigin from iframe.src at send time. If iframe.src is empty when you call host.sendEvent(...) or host.respond(...), the outbound is dropped with a console.warn. In React this is normally automatic (the iframe renders with src set). In vanilla JS, set iframe.src before the first outbound send.

Next steps

Messaging — Send events, handle requests, and observe the message flow.
Capability Handling — Declare capabilities, register handlers, and handle dynamic capability state.
Security — CSP, origin allowlist, transport, and token exchange.
API Reference — Detailed reference for BridgeHostProvider, hooks, and BridgeHost.

​React integration

​Using BridgeHostProvider

​Reading bridge state in components

​Listening for events

​Surfacing errors

​Dynamic journey URLs

​Multiple iframes on one page

​Framework-agnostic integration

​Vanilla JavaScript

​Vue 3 (Composition API)

​Angular

​Svelte

​Server-side rendering (Next.js, Remix, SvelteKit)

​Next.js (App Router)

​Next.js (Pages Router) and other SSR frameworks

​Lifecycle considerations

​Set up handlers before the journey requests them

​Detach when the iframe is removed

​Config snapshot at attach time

​iframe.src and outbound message timing

​Next steps

React integration

Using BridgeHostProvider

Reading bridge state in components

Listening for events

Surfacing errors

Dynamic journey URLs

Multiple iframes on one page

Framework-agnostic integration

Vanilla JavaScript

Vue 3 (Composition API)

Angular

Svelte

Server-side rendering (Next.js, Remix, SvelteKit)

Next.js (App Router)

Next.js (Pages Router) and other SSR frameworks

Lifecycle considerations

Set up handlers before the journey requests them

Detach when the iframe is removed

Config snapshot at attach time

iframe.src and outbound message timing

Next steps