# @gbg/go-bridge-web 中文文档

规范地址：https://npmcn.com/package/%40gbg/go-bridge-web/

版本：0\.2\.1
npm 元数据更新时间：2026-07-28T12:41:28.322Z
中文译文更新时间：2026-11-16T00:35:46.550Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gbg/go-bridge-web
原文对照：https://npmcn.com/package/%40gbg/go-bridge-web/?lang=original
项目主页：https://github.com/gbgplc/gbg-go-web-reference
源码仓库：https://github.com/gbgplc-internal/identity-gbggo-end-user-interaction

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：37.8 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-27T12:55:36.444Z
- 最新版本发布：2026-07-28T12:41:28.071Z
- 近 30 天下载量：3254（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

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

## 安装

```sh
npm install @gbg/go-bridge-web
```

也可以使用：`pnpm add @gbg/go-bridge-web`、`yarn add @gbg/go-bridge-web`、`bun add @gbg/go-bridge-web`

## README

# @gbg/去桥-web

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

使用反应? [`@gbg/go-bridge-web-react`](https://www.npmjs.com/package/@gbg/go-bridge-web-react) 用提供方和钩子包裹此包.

## 先决条件

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

## 安装

```bash
npm install @gbg/go-bridge-web
```

## 快开始

```html
<iframe
  id="journey"
  src="https://your-journey-url.example/…"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="camera"
></iframe>
```

```ts
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` (见 [安全说明](https://npmcn.com/package/%40gbg/go-bridge-web/#readme-security-notes); 如果 `src` 已经设定, 这个 重新装入 iframe 一次 .
-   输出消息是 **未排队**发送 `iframe.src` 设定 并带有控制台警告;后发送 `src` 已经设定,但之前 已经装入完成的行程可以默默地被 浏览器. 只有在行程开始后才发送事件——例如,在旅程结束后 第一个活动到达您:

```ts
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`数字 :

```ts
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` 观察交通和故障:

```ts
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 是什么？

主机页面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 和提交记录判断。

