# 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) ## 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 ### 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 ```json { "__ver": 1, "host": "mainpage.demo.supersdk.site", "version": "1.3.2", "md5": "9a0364b9e99bb480dd25e1f0284c8555", "size": 1048576, "pkg_path": "__super/mainpage.demo.supersdk.site@1.3.2@9a0364b9e99bb480dd25e1f0284c8555.zip" } ``` ### 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 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: ```json { "__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 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 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) 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`: ```json { "__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 --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. ## ZIP naming and toolchain constraints - **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. ## 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: `), 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 in `release_doc/supersdk/dev/Android/README.md` and `release_doc/supersdk/dev/iOS/README.md`. ## 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) |