SuperSDK Offline Package Remote Manifest Specification v1 (super_meta.json)
Status: Finalized v1 (Corresponding to Feature
SDK-F260716075511-Offline-Pkg-Spec-V1AC-1; Downstream consumers S6/CA-F024 generate the list according to this specification)
Overview
Section titled “Overview”super_meta.json is the sole contract for SuperSDK’s remote update capability: the site provider (e.g., S6/CA-F024 release pipelines) publishes this manifest at the site root path, while the SDK on both Android and iOS platforms asynchronously checks for this manifest in the background when opening the corresponding host app page, thereby determining whether a new version of the offline package is available for download and installation.
- Who produces it: The site release pipeline (e.g., S6/CA-F024), or generated synchronously when packaging locally using
packages/jssdk/super_package.sh(reference implementation, see below). - Who consumes: SuperSDK Android/iOS client (
OfflineRemoteUpdater, internal implementation, not exposed externally). - Format: Static JSON file under the site root path.
Data Structure
Section titled “Data Structure”Field Table
Section titled “Field Table”| Field | Type | Required | Validation rules | Default value | Note |
|---|---|---|---|---|---|
__ver | int | Yes | Must be == 1, otherwise the entire list is rejected. | - | The Manifest version format and the __ver in __super_meta.json within the package are two independent counters with no correlation. |
host | string | Yes | Must be exactly the same (case-insensitive) as the origin host of the detected site; otherwise, the entire list is rejected. | - | Intended solely for manifest self-verification of ownership; the SDK’s disk directory name uses only the actually detected origin host and never trusts this field for path concatenation. |
version | string | Yes | Exactly three ASCII digits x.y.z, total length ≤64 bytes; each segment, after removing any leading zeros, must satisfy major≤2147483647, minor/patch≤99. The raw string must exactly match __super_meta.json.app_version inside the zip package; if they differ during installation, the verification fails. | - | Offline package version number; 01.002.0003 and 1.2.3 have the same numeric value and cannot bypass the increment threshold. |
md5 | string | Yes | 32-character hexadecimal string, must exactly match the measured MD5 of the downloaded zip file. | - | zip file MD5 |
size | long | Yes | Must be > 0; in auto-detection mode, if > 50MB (50 * 1024 * 1024 bytes), skip the download (only explicit calls can download); if the actual byte count after download does not match this field, treat it as a checksum failure and clean up temporary files. | - | zip file byte count |
pkg_path | string | Yes | Site root-relative path, or a complete HTTPS URL (cross-origin CDN allowed); see the parsing rules below. | - | Package download location; do not change business ownership host. |
Minimal JSON example
Section titled “Minimal JSON example”{ "__ver": 1, "host": "mainpage.demo.supersdk.site", "version": "1.3.2", "md5": "9a0364b9e99bb480dd25e1f0284c8555", "size": 1048576,}Cross-domain CDN download
Section titled “Cross-domain CDN download”pkg_path supports both forms without adding new fields; __ver remains 1:
- Relative Path: Maintain existing rules; prohibit
://, paths starting with/(including//),..path segments, and backslashes; the SDK encodes and concatenates to formhttps://{origin host}/{pkg_path}. - Complete HTTPS URL: Allows any download domain without requiring a domain whitelist. Must be a valid, fully URL-encoded ASCII URL containing a valid host, with an explicit port range of 1–65535. Usernames, passwords, fragments, bare whitespace, and control characters are not accepted. Paths and query parameters are passed to the downloader as-is without re-encoding to preserve CDN signatures. HTTP, file, FTP, and
//cdn/...addresses without a scheme are not supported.
For example, the business site still provides the manifest under its own domain, but the package can be downloaded from the 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 still represents the business domain and cannot be changed to a CDN domain; installation directory, resource matching, and version threshold are all isolated according to the business origin host. Package size, MD5, package internal version, and decompression verification continue to take effect.
Compatibility: Full HTTPS URLs are supported starting from Android/iOS SDK 1.0.0.68-SNAPSHOT. Older SDKs will still reject absolute URLs; manifests serving legacy apps continue to use relative paths. The local super_package.sh and platform release pipelines still generate relative paths by default. When migrating to CDN, you can replace pkg_path; if the package content remains unchanged, the original MD5 and size are preserved.
Serve Location
Section titled “Serve Location”The manifest must be published at the site root path:
https://{host}/super_meta.json- A “Not Found” (404) status is a valid and common normal state (indicating the site is not connected to remote updates). The SDK handles it silently and does not treat it as an error.
- The path is fixed to the site root; the SDK does not support customizing the manifest path.
Relationship with the __super_meta.json file within the package
Section titled “Relationship with the __super_meta.json file within the package”In the offline package system, there are two meta files with distinct responsibilities that must not be confused:
super_meta.json (this specification) | __super_meta.json within the package | |
|---|---|---|
| Hierarchy | Transport Layer: Informs the SDK of the location, size, and fingerprint of the latest zip file. | Content Layer: Describes the file manifest within the zip, used for per-file verification during installation. |
| Location | Site root path, read before SDK downloads the zip | After the SDK extracts the zip package, it reads the contents. |
| Structure | Six Fields (this document) | {__ver, app_version, build_time, file_map} + optional remote_paths (automatically generated by super_package.sh) |
| Publisher | Site Publishing Pipeline (S6/CA-F024) | super_package.sh automatically writes to the target directory during packaging. |
They are cross-locked via version == app_version: the version declared in the manifest must match __super_meta.json.app_version inside the downloaded zip package; otherwise, the verification fails, and the locally installed older package will not be replaced.
remote_paths within the package: Network boundary under the package host (optional)
Section titled “remote_paths within the package: Network boundary under the package host (optional)”After the page is loaded using an offline package, all requests under the package host are treated as internal package resources by default: they are read only from the package version bound to that page. If the resource is not found in the package, an error is returned, and no fallback to the online site occurs. If the business API or remote media shares the same domain as the page, you must explicitly declare which paths are allowed to access the network in __super_meta.json within the package using remote_paths:
{ "__ver": 1, "app_version": "1.0.2", "build_time": 1794902284, "remote_paths": ["/api/", "/media/hero.mp4"], "file_map": { "index.html": { "length": 1234 } }}| Rules | Description |
|---|---|
| Type | String array, optional; up to 64 items |
| Item Format | Start with / but cannot be the root /; no .., ., empty segments, query strings, hashes, backslashes, or whitespace. |
| Match | Ends with / = directory prefix match (/api/ matches /api/chat, but not /apix/…); otherwise, exact match. |
| Matching Object | The original path of the request (excluding query / hash); requests decoded with . / .. segments are not considered remote paths. |
| Default | No network channels are available under the host app. |
| Invalid entry | Package verification failed; installation will not proceed. |
Package: bash super_package.sh <directory> <host> <version> --remote-path /api/ --remote-path /media/hero.mp4.
- Only constrain the host: Requests to other domains (API, CDN images/videos) are unaffected and continue to connect normally.
- Declarations follow the package version: The page binds to a specific version, and
remote_pathsis evaluated based on that version. - Android: Requests that match
remote_paths(any method) connect directly to the network; non-GET/HEADrequests that do not match return 405. - iOS: The origin of the offline page is
super-offline://{host}. Cross-origin requests without a network channel will return501+X-Super-Offline-Error: remote_path_unsupportedfor requests matchingremote_paths. For business APIs on the iOS offline page, please use absolute HTTPS URLs. - Supported starting from Android/iOS SDK
1.0.0.69-SNAPSHOT; earlier SDKs ignore this field. - Packages generated via the platform publishing pipeline (SuperSite deployment automatically generates offline packages) currently do not write
remote_paths. For same-domain networking requirements, please usesuper_package.shto package first.
ZIP naming and toolchain constraints
Section titled “ZIP naming and toolchain constraints”- Naming Convention: Package name is
{host}@{version}@{md5}.zip, release path is__super/{host}@{version}@{md5}.zip;super_package.shwrites the zip tooutput/__super/, and the rootoutput/super_meta.json’spkg_pathdefaults to this same-origin relative path; when publishing to CDN, it can be replaced with a full HTTPS URL. - Packaging Toolchain Constraints (Important): The zip file must be generated by a standard deflate compression tool (e.g.,
zip -r, consistent with the internal implementation ofsuper_package.sh). Streaming / data descriptor output methods are prohibited.- Cause: The iOS-side
ZipArchiveis a self-developed zip parser that scans and extracts in the order of local file headers, without reading the central directory. If a zip entry uses a data descriptor (wherecompressedSizeandcrc32are set to 0, and the actual values are written after the data block), the iOS parser cannot extract it correctly, causing the offline package to fail installation on iOS. - Any zip file generated by the
zipcommand-line tool (excluding-fd/streaming mode) or equivalent standard tools satisfies this constraint. Before using a custom streaming packaging script to generate a zip, you must verify on a real device that iOS can successfully decompress it.
- Cause: The iOS-side
SDK consumption behavior summary
Section titled “SDK consumption behavior summary”The following outlines the behavioral conventions for the SDK when consuming the dual-end receipt list, provided for the site to understand client-side behavior (detailed implementation is in the SDK’s internal technical solution and is not part of this specification’s contract):
| Behavior Item | Agreement |
|---|---|
| Detection timing | When the SDK opens any http(s) page, it asynchronously probes the host’s super_meta.json in the background during the page load hook (Android onPageStarted / iOS load(url:) + didStartProvisionalNavigation), without blocking page rendering. |
| Frequency Control Detection | Each host has a minimum interval of 30 minutes (process-internal timer, not persisted); probes within the interval are directly skipped (including 404/network failures, which also consume the interval to prevent repeated requests to sites without a manifest). |
| Automatic download limit | In auto-detection mode, if the manifest size exceeds 50MB, the download is skipped and only a log is recorded; explicitly calling the host app API (see below) can bypass this limit. |
| Business Ownership and Download Location | The host in the manifest must match the page origin host, and the disk storage also uses the origin host; pkg_path is appended to this host, and the complete HTTPS URL can point to an independent CDN. |
| Effective Time | After the new version is successfully installed and downloaded, it takes effect the next time the host page is loaded; it does not hot-refresh the currently open page. |
| Version Binding | A page (a single main document load) binds to the package version at the time of loading, persisting until the page is closed or the entire page is reloaded. During this period, downloading, verifying, or installing a new version does not affect its reading of the bound version; the old version files are retained until the last page using them is released. |
| Do not return to source | After binding the version, requests under the host app package except remote_paths can only read files within the package; if missing or read fails, an error response is returned (404 / 500 etc. + X-Super-Offline-Error: <reason>), without fetching from online sites or modifying the read of the new version. |
| No available package | No valid offline package available during host app loading: the page loads entirely from online resources (packages installed during this period are only available for subsequent new pages); when the host app explicitly requests offline mode (PageLoadConfig.requireOffline), display an error message with a retry entry point. |
| Failure Handling | Manifest 404 / Network Failure / Invalid Format / Validation Failed: In auto-detection mode, silent (logs only, no impact on page); old package remains usable; updates triggered by explicit host API calls that fail will notify the host via callbacks. |
Explicit trigger interface: Android
IOfflineController.preloadPackage(host, listener)/ corresponding iOS API, see the “Offline Package Remote Update” section inrelease_doc/supersdk/dev/Android/README.mdandrelease_doc/supersdk/dev/iOS/README.md.
Changelog
Section titled “Changelog”| Date | Change |
|---|---|
| 2026-11-17 | The package’s __super_meta.json now includes an optional remote_paths; the SDK’s consumption behavior adds page version binding, source blocking, and no available package (released with 1.0.0.69-SNAPSHOT). |
| 2026-11-11 | pkg_path supports cross-domain HTTPS URLs, preserving relative path compatibility and business host ownership validation; released with 1.0.0.68-SNAPSHOT (2026-11-12). |
| 2026-07-21 | v1 Finalized (Aligned with Feature SDK-F260716075511 AC-1 / S6 consumption anchor) |