跳到主要内容

App Bridge 概览

嵌入式应用是以 iframe 的形式嵌入在 Shoplazza 商家后台里运行的，而 iframe 内的页面与外层后台相互隔离，无法直接操作后台的导航、顶部操作条等。Shoplazza App Bridge 就是打通这层隔离的 JavaScript 库——在应用前端引入后，iframe 内的代码即可调用后台的导航跳转（Redirect）、返回链接（Backlink）、保存操作条（SaveBar），并获取调用 Open API 所需的鉴权令牌（Session Token），让你的应用用起来就像 Shoplazza 后台的原生页面，商家感觉不到自己离开过 Shoplazza。

你的应用什么时候需要 App Bridge？​

场景是否需要
应用 UI 嵌入到 Shoplazza 商家后台（iframe 内）✅ 必须
需要从应用内触发 Shoplazza 顶部导航/Redirect✅ 必须
应用是独立站点，商家通过外链跳出去使用❌ 不需要
纯后端服务、无 UI（仅通过 OAuth 后调 Open API）❌ 不需要

判断要点：你的应用在商家后台是不是以 iframe 形式展示？如果是，几乎必须用 App Bridge。

核心能力地图​

能力用途详细文档
Session Token嵌入式应用的鉴权——前端获取 JWT，后端验证，安全调用 Open APISession Token
Backlink在 Shoplazza 顶部导航增加一个"返回上一级"链接Backlink
SaveBar (Contextual Save Bar)表单脏检查 + 顶部统一的"保存/丢弃"操作条SaveBar
Redirect控制商家后台主导航跳转（保留 iframe 上下文）Redirect

与 Session Token 的关系​

浏览器（iframe）              你的应用后端
       │
       │ ① getSessionToken(clientID)
       │    （Shoplazza 签发 JWT，1 分钟有效）
       │
       │ ② fetch('/api/...', { Authorization: 'Bearer <jwt>' })
       │ ───────────────────────────────►
       │                                  ③ 验证 JWT
       │                                  ④ 用持久化的 access_token 调 Open API
       │                                  ⑤ 返回业务数据
       │ ◄───────────────────────────────

Session Token 生命周期固定 1 分钟——每次发请求都要重新获取，不要缓存。

安装​

App Bridge 以 npm 包 shoplazza-app-bridge 发布，在嵌入式应用的前端工程中安装：

npm install shoplazza-app-bridge --save

在应用入口文件中初始化（建议在页面挂载前执行一次）：

import { app } from 'shoplazza-app-bridge';

app.init();

app.init() 会向宿主（Shoplazza 商家后台）发送 APP::ENABLED 消息建立通信，并开始监听后台回传的事件。初始化后即可使用各项能力，具体用法见上方「核心能力地图」中链接的各页文档。

与 Shoplazza Admin UI 的一致性​

通过使用 App Bridge：

  • 应用看上去是 Shoplazza 后台的"原生页面"，商家心智一致
  • 浏览器历史、URL 跳转、保存提示都遵循商家熟悉的模式
  • 多语言、暗色模式（如 Shoplazza 支持）自动跟随宿主

与外链应用的区别​

嵌入式（App Bridge）外链应用（无 App Bridge）
商家入口在 Shoplazza 后台左侧导航点进来跳出 Shoplazza 到独立站点
视觉一致与 Admin UI 一致独立设计
鉴权Session Token + 持久 access_token仅 access_token
推荐场景商家在 Shoplazza 工作流中频繁使用的应用偶尔使用、需独立 UX 的工具

相关​