# App Bridge 概览

> 嵌入式 Shoplazza 应用何时需要 App Bridge，这个 JavaScript 库提供的 Session Token、Backlink、SaveBar、Redirect 能力，以及安装方式。

[嵌入式应用](/docs/app/getting-started/app-types#embedded-apps-method)是以 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 API | [Session Token](/docs/app/developer-tools/app-bridge/session-token) |
| **Backlink** | 在 Shoplazza 顶部导航增加一个"返回上一级"链接 | [Backlink](/docs/app/developer-tools/app-bridge/actions/backlink) |
| **SaveBar (Contextual Save Bar)** | 表单脏检查 + 顶部统一的"保存/丢弃"操作条 | [SaveBar](/docs/app/developer-tools/app-bridge/actions/contextual-save-bar) |
| **Redirect** | 控制商家后台主导航跳转（保留 iframe 上下文） | [Redirect](/docs/app/developer-tools/app-bridge/actions/redirect) |

## 与 Session Token 的关系

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

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

## 安装

App Bridge 以 npm 包 [`shoplazza-app-bridge`](https://www.npmjs.com/package/shoplazza-app-bridge) 发布，在嵌入式应用的前端工程中安装：

```bash
npm install shoplazza-app-bridge --save
```

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

```javascript
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 的工具 |

## 相关

- [Session Token 详解](/docs/app/developer-tools/app-bridge/session-token)
- [应用类型选型](/docs/app/getting-started/app-types)
- [OAuth 鉴权](/docs/app/building-blocks/authentication/oauth-flow) — 应用第一次安装时获取 access_token