跳转到内容

SuperSDK 离线包远程清单规范 v1(super_meta.json)

状态:定稿 v1(对应 Feature SDK-F260716075511-Offline-Pkg-Spec-V1 AC-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 文件。
字段类型必填校验规则默认值备注
__verint是必须 == 1,否则整份清单被拒绝-清单格式版本号,与包内 __super_meta.json 的 __ver 是两套独立计数,互不关联
hoststring是必须与被探测站点的 origin host 完全一致(大小写不敏感);不一致则整份清单被拒绝-仅用于清单自证归属;SDK 落盘目录名只取实际探测到的 origin host,永远不信任此字段做路径拼接
versionstring是恰三段 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 数值同值,不能绕过递增水位
md5string是32 位十六进制字符串,须与下载后 zip 文件的实测 MD5 完全一致-zip 文件 MD5
sizelong是必须 > 0;自动探测模式下若 > 50MB(50 * 1024 * 1024 字节)则跳过下载(仅显式调用可下);下载完成后若实际字节数与本字段不符,按校验失败处理并清理临时文件-zip 文件字节数
pkg_pathstring是站点根相对路径,或完整的 HTTPS URL(允许跨域 CDN);解析规则见下文-包的下载位置;不改变业务归属 host
{
"__ver": 1,
"host": "mainpage.demo.supersdk.site",
"version": "1.3.2",
"md5": "9a0364b9e99bb480dd25e1f0284c8555",
"size": 1048576,
"pkg_path": "__super/[email protected]@9a0364b9e99bb480dd25e1f0284c8555.zip"
}

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 和大小。

清单必须发布在站点根路径:

https://{host}/super_meta.json
  • 不存在(404)是合法且常见的正常状态(表示该站点未接入远程更新),SDK 静默处理,不视为错误。
  • 路径固定为站点根,SDK 不支持自定义清单路径。

离线包体系里存在两份 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 打包。
  • 命名规则:包名为 {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 侧可正常解压。

以下是 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-11pkg_path 支持跨域 HTTPS URL,保留相对路径兼容与业务 host 归属校验;随 1.0.0.68-SNAPSHOT 发布(2026-11-12)
2026-07-21v1 定稿(对齐 Feature SDK-F260716075511 AC-1 / S6 消费锚点)