SuperSDK 离线包远程清单规范 v1(super_meta.json)
状态:定稿 v1(对应 Feature
SDK-F260716075511-Offline-Pkg-Spec-V1AC-1;下游消费方 S6/CA-F024 按本规范产出清单)
super_meta.json 是 SuperSDK 离线包远程更新能力的唯一契约:站点方(S6/CA-F024 等发布管道)在站点根路径发布这份清单,SDK 双端(Android / iOS)在打开对应 host 的页面时后台探测该清单,据此判断是否有新版离线包可下载安装。
- 谁产出:站点发布管道(如 S6/CA-F024),或本地用
packages/jssdk/super_package.sh打包时同步生成(参考实现,见下文)。 - 谁消费:SuperSDK Android / iOS 客户端(
OfflineRemoteUpdater,内部实现,不对外暴露)。 - 格式:站点根路径下的静态 JSON 文件。
| 字段 | 类型 | 必填 | 校验规则 | 默认值 | 备注 |
|---|---|---|---|---|---|
__ver | int | 是 | 必须 == 1,否则整份清单被拒绝 | - | 清单格式版本号,与包内 __super_meta.json 的 __ver 是两套独立计数,互不关联 |
host | string | 是 | 必须与被探测站点的 origin host 完全一致(大小写不敏感);不一致则整份清单被拒绝 | - | 仅用于清单自证归属;SDK 落盘目录名只取实际探测到的 origin host,永远不信任此字段做路径拼接 |
version | string | 是 | 恰三段 ASCII 数字 x.y.z,总长 ≤64 bytes;各段去任意前导零后按数值限制 major≤2147483647、minor/patch≤99。raw string 必须与 zip 包内 __super_meta.json.app_version 完全相等,安装时不等按校验失败处理 | - | 离线包版本号;01.002.0003 与 1.2.3 数值同值,不能绕过递增水位 |
md5 | string | 是 | 32 位十六进制字符串,须与下载后 zip 文件的实测 MD5 完全一致 | - | zip 文件 MD5 |
size | long | 是 | 必须 > 0;自动探测模式下若 > 50MB(50 * 1024 * 1024 字节)则跳过下载(仅显式调用可下);下载完成后若实际字节数与本字段不符,按校验失败处理并清理临时文件 | - | zip 文件字节数 |
pkg_path | string | 是 | 站点根相对路径,或完整的 HTTPS URL(允许跨域 CDN);解析规则见下文 | - | 包的下载位置;不改变业务归属 host |
最小 JSON 示例
Section titled “最小 JSON 示例”{ "__ver": 1, "host": "mainpage.demo.supersdk.site", "version": "1.3.2", "md5": "9a0364b9e99bb480dd25e1f0284c8555", "size": 1048576,}跨域 CDN 下载
Section titled “跨域 CDN 下载”pkg_path 同时支持两种形式,不新增字段,__ver 仍为 1:
- 相对路径:保持既有规则,禁止
://、以/开头(含//)、..路径段和反斜杠;SDK 编码后拼成https://{origin host}/{pkg_path}。 - 完整 HTTPS URL:允许任意下载域,无需域名白名单。必须是合法、已完成 URL 编码的 ASCII URL,包含有效主机,显式端口范围为 1–65535;不接受用户名/密码、fragment、裸空白或控制字符。路径和查询参数原样传给下载器,不进行二次编码,以保留 CDN 签名。HTTP、file、FTP 和省略 scheme 的
//cdn/...地址不支持。
例如,业务站点仍在自己的域名下提供清单,但包可以从 CDN 下载:
{ "__ver": 1, "host": "mainpage.demo.supersdk.site", "version": "1.3.2", "md5": "9a0364b9e99bb480dd25e1f0284c8555", "size": 1048576, "pkg_path": "https://cdn.example.com/packages/app-1.3.2.zip?token=a%2Fb%3D&expires=123"}host 仍表示业务域名,不能改成 CDN 域名;安装目录、资源匹配、版本水位均按业务 origin host 隔离。包的大小、MD5、包内版本和解压校验继续生效。
兼容性:完整 HTTPS URL 自 Android/iOS SDK 1.0.0.68-SNAPSHOT 起支持。旧 SDK 仍会拒绝绝对 URL;服务旧 App 的清单继续使用相对路径。本地 super_package.sh 和平台发布管道默认仍生成相对路径,迁到 CDN 时可替换 pkg_path,包内容不变则保留原 MD5 和大小。
Serve 位置
Section titled “Serve 位置”清单必须发布在站点根路径:
https://{host}/super_meta.json- 不存在(404)是合法且常见的正常状态(表示该站点未接入远程更新),SDK 静默处理,不视为错误。
- 路径固定为站点根,SDK 不支持自定义清单路径。
与包内 __super_meta.json 的关系
Section titled “与包内 __super_meta.json 的关系”离线包体系里存在两份 meta,职责不同、不能混淆:
super_meta.json(本规范) | 包内 __super_meta.json | |
|---|---|---|
| 层次 | 传输层:告诉 SDK「最新版 zip 在哪、多大、指纹是什么」 | 内容层:描述 zip 内部文件清单,用于安装时逐文件校验 |
| 位置 | 站点根路径,SDK 下载 zip 之前读取 | zip 包内部,SDK 解压之后读取 |
| 结构 | 六字段(本文档) | {__ver, app_version, build_time, file_map} + 可选 remote_paths(由 super_package.sh 自动生成) |
| 产出方 | 站点发布管道(S6/CA-F024) | super_package.sh 打包时自动写入目标目录 |
两者通过 version == app_version 交叉锁定:清单声明的 version 必须与下载到的 zip 包内 __super_meta.json.app_version 一致,否则视为校验失败,不会替换本地已安装的旧包。
包内 remote_paths:包 host 下的联网边界(可选)
Section titled “包内 remote_paths:包 host 下的联网边界(可选)”页面使用离线包加载后,包 host 下的请求默认全部是包内资源:只从该页面绑定的包版本读取,包里没有就返回错误,不会回源到线上站点。如果业务 API 或远程媒体与页面同域,需要在包内 __super_meta.json 用 remote_paths 显式声明哪些路径允许联网:
{ "__ver": 1, "app_version": "1.0.2", "build_time": 1794902284, "remote_paths": ["/api/", "/media/hero.mp4"], "file_map": { "index.html": { "length": 1234 } }}| 规则 | 说明 |
|---|---|
| 类型 | 字符串数组,可省略;最多 64 项 |
| 条目格式 | 以 / 开头且不能是根 /;不含 .. / . / 空段、query、hash、反斜杠、空白 |
| 匹配 | 以 / 结尾 = 目录前缀匹配(/api/ 命中 /api/chat,不命中 /apix/…);否则精确匹配 |
| 匹配对象 | 请求的原始路径(不含 query / hash);解码后带 . / .. 段的请求一律不算远程路径 |
| 缺省 | 包 host 下没有任何联网通道 |
| 非法条目 | 整包校验失败,不会安装 |
打包:bash super_package.sh <directory> <host> <version> --remote-path /api/ --remote-path /media/hero.mp4。
- 只约束包 host:其他域名的请求(API、CDN 图片/视频)不受影响,照常联网。
- 声明随包版本走:页面绑定哪个版本,就按那个版本的
remote_paths判定。 - Android:命中
remote_paths的请求(任意方法)直接联网;未命中的非GET/HEAD请求返回 405。 - iOS:离线页 origin 是
super-offline://{host},同域请求没有联网通道,命中remote_paths的请求返回501+X-Super-Offline-Error: remote_path_unsupported;iOS 离线页的业务 API 请使用绝对 https URL。 - 自 Android/iOS SDK
1.0.0.69-SNAPSHOT起支持;更早的 SDK 忽略该字段。 - 经平台发布管道(SuperSite 部署自动生成离线包)产出的包目前不写
remote_paths,同域联网需求请先用super_package.sh打包。
zip 命名与工具链约束
Section titled “zip 命名与工具链约束”- 命名规则:包名为
{host}@{version}@{md5}.zip,发布路径为__super/{host}@{version}@{md5}.zip;super_package.sh将 zip 写入output/__super/,根output/super_meta.json的pkg_path默认指向这个同源相对路径;发布到 CDN 时可替换为完整 HTTPS URL。 - 打包工具链约束(重要):zip 必须由标准 deflate 压缩工具产出(如
zip -r,与super_package.sh内部实现一致),禁止使用流式写出(streaming / data descriptor)方式产 zip。- 原因:iOS 端
ZipArchive是自研的 zip 解析器,按 local file header 顺序扫描解压,不读取 central directory;若 zip 条目使用 data descriptor(compressedSize/crc32置 0,实际值写在数据块之后),iOS 解析器无法正确解压,会导致离线包在 iOS 上安装失败。 - 凡是经
zip命令行工具(非-fd/流式模式)或等价标准工具产出的 zip 均满足本约束;用自定义流式打包脚本产 zip 前,务必先用真机联测验证 iOS 侧可正常解压。
- 原因:iOS 端
SDK 消费行为摘要
Section titled “SDK 消费行为摘要”以下是 SDK 双端消费本清单时的行为约定,供站点方理解客户端表现(详细实现见 SDK 内部技术方案,不属于本规范的契约内容):
| 行为项 | 约定 |
|---|---|
| 探测时机 | SDK 打开任意 http(s) 页面时,在页面加载 hook(Android onPageStarted / iOS load(url:) + didStartProvisionalNavigation)后台异步探测该 host 的 super_meta.json,不阻塞页面渲染 |
| 探测频控 | 每个 host 最小间隔 30 分钟(进程内计时,不持久化);间隔内的探测直接跳过(含 404/网络失败也占用该间隔,避免无清单站点被反复请求) |
| 自动下载上限 | 自动探测模式下,清单 size 超过 50MB 时跳过下载,仅记录日志;显式调用宿主 API(见下)可绕过该上限 |
| 业务归属与下载位置 | 清单 host 必须与页面 origin host 一致,落盘也使用 origin host;相对 pkg_path 拼接到该 host,完整 HTTPS URL 可指向独立 CDN |
| 生效时机 | 新版本下载安装成功后,下次加载该 host 页面时生效;不会热刷新当前已打开的页面 |
| 版本绑定 | 页面(一次主文档加载)在加载时绑定当时的包版本,直到页面关闭或整页重新加载;期间下载、校验、安装新版本都不影响它读取已绑定的版本,旧版本文件保留到最后一个使用它的页面释放 |
| 禁止回源 | 绑定版本后,包 host 下除 remote_paths 外的请求只读包内文件;缺失或读取失败返回错误响应(404 / 500 等 + X-Super-Offline-Error: <原因>),不向线上站点补取,也不改读新版本 |
| 无可用包 | 加载时该 host 没有有效离线包:页面全程按线上页面加载(期间装好的包只供之后的新页面使用);宿主显式要求离线(PageLoadConfig.requireOffline)时显示错误与重试入口 |
| 失败处理 | 清单 404 / 网络失败 / 格式非法 / 校验不通过:自动探测模式下静默(仅记日志,不影响页面),旧包保持可用;显式调用宿主 API 触发的更新失败会通过回调通知宿主 |
显式触发接口:Android
IOfflineController.preloadPackage(host, listener)/ iOS 对应 API,详见release_doc/supersdk/dev/Android/README.md、release_doc/supersdk/dev/iOS/README.md的「离线包远程更新」章节。
| 日期 | 变更 |
|---|---|
| 2026-11-17 | 包内 __super_meta.json 新增可选 remote_paths;SDK 消费行为补充页面版本绑定、禁止回源、无可用包三项(随 1.0.0.69-SNAPSHOT 发布) |
| 2026-11-11 | pkg_path 支持跨域 HTTPS URL,保留相对路径兼容与业务 host 归属校验;随 1.0.0.68-SNAPSHOT 发布(2026-11-12) |
| 2026-07-21 | v1 定稿(对齐 Feature SDK-F260716075511 AC-1 / S6 消费锚点) |