@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除非你的旅程需要他们. - 允许摄像头进入. 捕捉文档或自拍的行程
浏览器调用
getUserMediaiframe 内部,一个跨源 iframe 只能使用权限政策赠款: setallow="camera"框架(和microphone如果你的行程记录 录音). 没有它,捕捉失败 在旅程中. - URL参数. 当主机附加时, SDK 附加
gbggoSource(SDK名称/版本和嵌入主机)和gbggoHostOrigin(您的页面来源) 查询参数到 iframesrc,这样旅程就可以识别它嵌入的东西。 发生这种事 每个附件一次,相对当前(或第一指定)src: 如果您认为 稍后你重新点 自己,打电话attach(iframe)再来一次 别 剥去这些参数.
生命周期
attach(iframe) ——建筑师号召你——将宿主捆绑在..
一个 iframe 并开始监听; 您可以再次调用它来重新组合( 待定)
状态被保留). 打电话 detach() 完成后:SDK安装一个
window message 保留主机实例的监听器(以及
它的信息缓冲器) 活到页面的寿命.
许可证
麻省理工学院 GBG Group plc