@gbg/go-bridge-web

中文文档
0.2.1发布于 2026/07/28MITTypeScriptES Module零依赖近 30 天下载 3254

主机页面SDK用于将GBG GO身份验证行程通过iframe嵌入到网络应用中. 框架-不可知核 有类型安全的桥接通讯协议.

中文使用文档
文档目录10 节
  1. 先决条件
  2. 安装
  3. 快开始
  4. 如何运作
  5. 能力发现
  6. 处理请求
  7. 监视交通和错误
  8. 安全说明
  9. 生命周期
  10. 许可证

@gbg/去桥-web

嵌入主机页面 SDK GBG 前进 身份 通过iframe在网络应用程序中验证行程。 框架不可知性, 零依赖关系, 并有已键入的桥接通讯协议 postMessage。 。 。 .

使用反应? @gbg/go-bridge-web-react 用提供方和钩子包裹此包.

先决条件

你需要一个GBG GO协议和一个配置的行程. 您加载的 URL 进入iframe——因此你的允许列表的来源——来自 您的 GBG GO 行程配置; 您的 GBG 整合联系人可以 提供它,连同一组桥梁行动 你的具体旅程 发送.

安装

npm install @gbg/go-bridge-web

快开始

<iframe
  id="journey"
  src="https://your-journey-url.example/…"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="camera"
></iframe>
import { BridgeHost } from '@gbg/go-bridge-web';

const iframe = document.querySelector<HTMLIFrameElement>('#journey');
if (!iframe) throw new Error('journey iframe not found');

const host = new BridgeHost({
  iframe,
  // Origins the journey is served from. Required, must be non-empty.
  allowedOrigins: ['https://your-journey-origin.example'],
  // Identifies your host app in capability.query responses.
  hostVersion: 'my-app-1.0.0',
  // Capabilities your page offers the journey (all optional).
  capabilities: {
    'analytics.forward': { supported: true, version: '1.0' },
  },
});

// Handle requests the journey sends to your page.
host.registerHandler('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({});
  },
});

// When the host is no longer needed:
host.detach();

在你第一次发信前要知道两件事:

  • 构造iframe 中的主机附件桥参数 src (见 安全说明; 如果 src 已经设定, 这个 重新装入 iframe 一次 .
  • 输出消息是 未排队发送 iframe.src 设定 并带有控制台警告;后发送 src 已经设定,但之前 已经装入完成的行程可以默默地被 浏览器. 只有在行程开始后才发送事件——例如,在旅程结束后 第一个活动到达您:
let journeyReady = false;
host.delegate = {
  onMessage: (h, message) => {
    if (message.type === 'event' && !journeyReady) {
      journeyReady = true;
      h.sendEvent('host.locale.update', { locale: 'en-GB' });
    }
  },
};

如何运作

SDK用嵌入式行程交换 JSON 消息 window.postMessage每个消息都带有协议版本, a correlationId页:1 type和有效载荷:

  • request (出行-主持人)——旅程请主持人做 比如说前方分析事件 主机通过一个 response 同样的 correlationId。 。 。 .
  • response (主机)——终点站状态为: success, (中文(简体) ), error, (中文(简体) ), cancelled,以及 unsupported· ; acknowledged 是临时 长期工作状况.
  • event (两个方向)——火灾和遗忘通知,例如 行程寿命周期变化或主机地块更新。 见 BridgeActions 对知名的行动识别器.

带不同协议版本的邮件都会被处理, 有个控制台警告 当前版本导出为 BridgeHost.PROTOCOL_VERSION。 。 。 .

能力发现

行程通过发送一个 capability.query 请求。 SDK 自动从 capabilities 将地图传送到构造器中, 加上以后添加的任何内容 与 registerCustomCapability(id, version?, handler?) 身份证明 在两者中,构造器地图优先。 众所周知的能力 标识符导出为 CAPABILITY_IDS (单位:千美元)camera.document, (中文(简体) ), camera.selfie, (中文(简体) ), nfc.read, (中文(简体) ), biometric.auth, (中文(简体) ), device.attestation, (中文(简体) ), location.gps, (中文(简体) ), storage.secure, (中文(简体) ), analytics.forward) (中文(简体) ).

注:仅限 supported, (中文(简体) ), version,以及 permissionState a 区域 CapabilityInfo 传送至行程; constraints 实值 仅限主机侧.

处理请求

需要什么动作(如果有的话) 旅行发送取决于 行程被配置 – 用您的 GBG 集成确认设定 联络 每个动作注册一个处理器 registerHandler(action, handler)。处理器接收原始 BridgeMessage (单位:千美元) BridgeResponder数字 :

host.registerHandler('camera.document.capture', {
  handle: async (request, responder) => {
    responder.acknowledge(); // interim: tell the journey work has started
    try {
      // captureDocument() is your implementation — the SDK does not
      // provide capture UI.
      const result = await captureDocument();
      responder.success({ imageRef: result.ref });
    } catch (err) {
      responder.error({
        code: 'INTERNAL_ERROR',
        message: String(err),
        recoverable: false,
      });
    }
  },
});

答复者最多发送一个终端答复——在 success 编号 : error 编号 : cancelled 编号 : unsupported,进一步呼吁 没有。 如果操作者在前方抛出(或背弃) 响应, SDK 代表它发送错误回复(代码) HANDLER_FAILURE,其中的行走表面 是一个内部错误) 旅程不是离开等待.

没有注册处理器的请求已排入队列 host.pendingRequests (最多50起;超过此数者,通过代表处删除并报告) onError并浮出水面通过代表的 onUnhandledRequest。 。 。 你 可以稍后以 host.respond({ correlationId, status, data })。 。 。 .

监视交通和错误

传出 a BridgeHostDelegate 观察交通和故障:

const host = new BridgeHost({
  iframe,
  allowedOrigins: ['https://your-journey-origin.example'],
  delegate: {
    onMessage: (host, message) => console.debug('in', message),
    onMessageSent: (host, message) => console.debug('out', message),
    onUnhandledRequest: (host, request) => console.warn('unhandled', request),
    onError: (host, error) => console.error(error),
  },
});

onError 处理者投掷的火(在发出答复之前), 代表抛出,和 postMessage 例外情况。 已丢弃的发送 原因(无) src 然而, 来源不允许列出) 表面为控制台 警告,然后发出 detach() 静静地放弃.

host.receivedMessages (最后200条入境信息), host.pendingRequests,以及 host.lastError 揭露同样的信息 用于投票式调试。 注意缓冲: 消息有效载荷留在 页面的内存,直到剪切或主机发布.

安全说明

  • allowedOrigins 您的信任边界. 来自任何 其他来源被忽略,出局发送验证 iframe 的当前 src 源代码与许可列表相悖 —— 因此重新指定的iframe 无法接收 桥载荷。 条目必须是 http(s) 来源; 通配符, 如 * 在构建时被拒绝,而 URL 形状的条目将正常化 直至他们的起源.
  • 沙盒里装着自己. SDK没有设置 sandbox 属性. sandbox="allow-scripts allow-same-origin allow-forms" 是一个 合理的起点。 因为旅程是跨出源的, allow-same-origin 沙盒只放轻松 旅程 来源 (它需要自己的存储和饼干) 不是你的。 添加 allow-modals 编号 : allow-popups 除非你的旅程需要他们.
  • 允许摄像头进入. 捕捉文档或自拍的行程 浏览器调用 getUserMedia iframe 内部,一个跨源 iframe 只能使用权限政策赠款: set allow="camera" 框架(和 microphone 如果你的行程记录 录音). 没有它,捕捉失败 在旅程中.
  • URL参数. 当主机附加时, SDK 附加 gbggoSource (SDK名称/版本和嵌入主机)和 gbggoHostOrigin (您的页面来源) 查询参数到 iframe src,这样旅程就可以识别它嵌入的东西。 发生这种事 每个附件一次,相对当前(或第一指定) src: 如果您认为 稍后你重新点 自己,打电话 attach(iframe) 再来一次 别 剥去这些参数.

生命周期

attach(iframe) ——建筑师号召你——将宿主捆绑在.. 一个 iframe 并开始监听; 您可以再次调用它来重新组合( 待定) 状态被保留). 打电话 detach() 完成后:SDK安装一个 window message 保留主机实例的监听器(以及 它的信息缓冲器) 活到页面的寿命.

许可证

麻省理工学院 GBG Group plc

版本与发布记录

@gbg/go-bridge-web 共发布 2 个版本,首次发布于 2026/07/27;过去 12 个月发布了 2 个版本。

版本发布日期距今
0.2.1latest2026/07/283 个月前
0.2.02026/07/273 个月前

关于 @gbg/go-bridge-web 的常见问题

@gbg/go-bridge-web 是什么?

主机页面SDK用于将GBG GO身份验证行程通过iframe嵌入到网络应用中. 框架-不可知核 有类型安全的桥接通讯协议.

如何安装 @gbg/go-bridge-web?

在项目目录运行 npm install @gbg/go-bridge-web,或使用 pnpm add / yarn add / bun add。

@gbg/go-bridge-web 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gbg/go-bridge-web 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gbg/go-bridge-web 可以商用吗?

@gbg/go-bridge-web 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gbg/go-bridge-web 的下载量有多少?

根据 npm 官方下载统计,@gbg/go-bridge-web 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,254 次,日均约 108 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gbg/go-bridge-web 还在维护吗?

最新版本 0.2.1 发布于 2026/07/28(3 个月前);至今共发布 2 个版本,其中过去 12 个月发布了 2 个;首次发布于 2026/07/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。