Skip to content

SuperSDK Offline Package Remote Manifest Specification v1 (super_meta.json)

Status: Finalized v1 (Corresponding to Feature SDK-F260716075511-Offline-Pkg-Spec-V1 AC-1; Downstream consumers S6/CA-F024 generate the list according to this specification)

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.
FieldTypeRequiredValidation rulesDefault valueNote
__verintYesMust 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.
hoststringYesMust 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.
versionstringYesExactly 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.
md5stringYes32-character hexadecimal string, must exactly match the measured MD5 of the downloaded zip file.-zip file MD5
sizelongYesMust 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_pathstringYesSite 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.
{
"__ver": 1,
"host": "mainpage.demo.supersdk.site",
"version": "1.3.2",
"md5": "9a0364b9e99bb480dd25e1f0284c8555",
"size": 1048576,
"pkg_path": "__super/[email protected]@9a0364b9e99bb480dd25e1f0284c8555.zip"
}

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 form https://{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.

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
HierarchyTransport 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.
LocationSite root path, read before SDK downloads the zipAfter the SDK extracts the zip package, it reads the contents.
StructureSix Fields (this document){__ver, app_version, build_time, file_map} + optional remote_paths (automatically generated by super_package.sh)
PublisherSite 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 } }
}
RulesDescription
TypeString array, optional; up to 64 items
Item FormatStart with / but cannot be the root /; no .., ., empty segments, query strings, hashes, backslashes, or whitespace.
MatchEnds with / = directory prefix match (/api/ matches /api/chat, but not /apix/…); otherwise, exact match.
Matching ObjectThe original path of the request (excluding query / hash); requests decoded with . / .. segments are not considered remote paths.
DefaultNo network channels are available under the host app.
Invalid entryPackage 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_paths is evaluated based on that version.
  • Android: Requests that match remote_paths (any method) connect directly to the network; non-GET/HEAD requests 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 return 501 + X-Super-Offline-Error: remote_path_unsupported for requests matching remote_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 use super_package.sh to package first.
  • Naming Convention: Package name is {host}@{version}@{md5}.zip, release path is __super/{host}@{version}@{md5}.zip; super_package.sh writes the zip to output/__super/, and the root output/super_meta.json’s pkg_path defaults 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 of super_package.sh). Streaming / data descriptor output methods are prohibited.
    • Cause: The iOS-side ZipArchive is 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 (where compressedSize and crc32 are 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 zip command-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.

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 ItemAgreement
Detection timingWhen 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 DetectionEach 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 limitIn 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 LocationThe 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 TimeAfter 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 BindingA 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 sourceAfter 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 packageNo 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 HandlingManifest 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 in release_doc/supersdk/dev/Android/README.md and release_doc/supersdk/dev/iOS/README.md.

DateChange
2026-11-17The 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-11pkg_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-21v1 Finalized (Aligned with Feature SDK-F260716075511 AC-1 / S6 consumption anchor)