55 lines
3.7 KiB
Markdown
55 lines
3.7 KiB
Markdown
# SGS Map SDK 交付包
|
||
|
||
> **版本**：V2.0.0
|
||
> **定位**：深圳自然博物馆统一三维高精地图导航服务平台 H5 SDK
|
||
|
||
欢迎接入 SGS Map SDK！本 SDK 将复杂的 WebGL 三维渲染、GLB 模型管线与 NavMesh 物理寻路引擎封装在服务端基座中，业务端（H5 / 大屏 / 小程序）只需通过几行代码即可极速唤起 3D 地图。
|
||
|
||
## 📁 目录结构
|
||
|
||
```text
|
||
sgs-map-sdk-release/
|
||
├── dist/ # SDK 代码产物包（核心）
|
||
│ ├── index.global.js # 给大屏端或传统网页使用的 IIFE 格式（通过 <script> 引入）
|
||
│ ├── index.global.js.map # IIFE source map
|
||
│ ├── index.mjs # 给 Webpack / Vite / Next.js 等现代工程使用的 ESM 格式
|
||
│ ├── index.mjs.map # ESM source map
|
||
│ ├── index.d.ts # TypeScript 类型声明文件
|
||
│ └── index.d.mts # TypeScript 模块声明文件
|
||
├── example/
|
||
│ └── index.html # 完整接入示例（带控制台、日志面板、与后端 API 联调）
|
||
├── package.json # NPM 元信息
|
||
├── sdk-quickstart.md # 【必读】10 分钟快速接入指南（含完整示例代码）
|
||
├── sdk-protocol.md # 【选读】底层通信协议与安全沙箱规范说明
|
||
└── README.md # 当前说明文档
|
||
```
|
||
|
||
## 🚀 环境对接配置信息 (非常重要)
|
||
|
||
在下游业务端执行 `new SGSMapSDK({ ... })` 初始化时，必须要填入由服务端分配的**环境对接变量**：
|
||
|
||
1. **`sdkUrl`（渲染基座地址）**：
|
||
- 释义：独立渲染基座的 URL 路径，SDK 会自动在您的页面中创建一个不可见的 iframe 或 Web-View 连接到这里。
|
||
- **请联系地图管理平台管理员获取最新的正式/测试域名**，例如：`https://map.museum.com/h5-sdk`。
|
||
|
||
2. **`targetOrigin`（安全通信域）**：
|
||
- 释义：这是指**地图渲染基座的来源域名**（即 `sdkUrl` 的 Origin）。为了安全，SDK 只接收来自该域名 iframe 的消息。
|
||
- 配置要求：请传入您的地图基座部署域名，例如：`https://map.museum.com`。如果不传，SDK 会自动从 `sdkUrl` 参数推导。注意：**不要**填成您业务页面的域名（业务页面的域名是交给 h5-sdk 做白名单校验的）。
|
||
|
||
## 📦 独立渲染基座部署与版本关系
|
||
|
||
- **部署要求**：本 SDK 是“双域架构”。除了在您的业务前端引入 `sgs-map-sdk` 库以外，**SGS 统一地图管理平台必须在您的服务器或内网环境中完成独立部署**（基座项目为 `sgs-frontend-map`）。
|
||
- **版本对应**：SDK 与基座严格遵守大版本一致原则。例如，SDK `V2.x.x` 必须对应基座引擎的 `V2.x.x`。如果强行跨版本混用，`HELLO` 协议握手将被拒绝并抛出 `ERR_NOT_READY`。
|
||
|
||
## 📚 如何开始？
|
||
|
||
- **如果您是普通前端业务开发 / 微信小程序开发**：
|
||
直接打开 `sdk-quickstart.md`，复制里面的示例代码，10分钟即可完成接入。
|
||
*(注：微信小程序团队完全无需引入 `dist` 下的代码，请仔细阅读文档中小程序 `<web-view>` 的原生接入方式)*
|
||
|
||
- **如果您想看一份能直接跑的完整示例**：
|
||
打开 `example/index.html`，用本地静态服务器（如 `npx serve`）打开即可，里面包含楼层切换、聚焦、寻路、图钉、超时、销毁等全场景演示。需要先把基座 `sgs-frontend-map` 跑起来并把 `sdkUrl` 改成对应的本地地址。
|
||
|
||
- **如果您是对架构感兴趣的高级开发**：
|
||
可以阅读 `sdk-protocol.md`，了解我们如何通过双域确权协议解决 `postMessage` 多实例安全问题，以及 WebGL 的安全释放机制。
|