This specification defines how MiniApps are located, which is called MiniApp Addressing, including the specifications for specific MiniApp URI syntax components based on the URI specification and the process to dereference the MiniApp URI. Implementing this specification enables the user agent to locate MiniApp resources.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
Publication as a First Public Working Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
MiniApps are applications that run on the user agent and are based on Web technology combined with native application technology. The [MINIAPP-PACKAGING] specification defines the form of resources in the MiniApp, the specific path in the MiniApp, and the mapped path relationship in the MiniApp URI scheme.
The source the user agent uses to get the MiniApp package is called the package provider.
MiniApp Addressing is a technology that uniquely corresponds to a specific resource within a MiniApp. The MiniApp Addressing uses mobile deep linking technology. The prefix of the URI depends on how the device system supports it and which is selected by the user agent. The rest follows the specification in the syntax section, which describes the specifications and definitions of some syntax components of the URI in the MiniApp. Parts not covered in these specifications follow the URI specifications and are not repeated here.
<!doctype html><html><ahref="platform://miniapp/foo;version=1.0.1-trial/pages/index?category=book#section-3">open a MiniApp</a></html>
An a element with the href attribute is embedded as the MiniApp URI on the web page. When a user clicks the link, if the environment on which the web page is running cannot handle the URL, the OS will distribute it to a proper user agent based on the URI prefix. The user agent receives the URI and dereferences it. Based on the host, id, and version in the URI, a request is made to a specific package server that can provide MiniApp package upload and download services to download and open the corresponding MiniApp.
As shown in the following flowchart, the package is a collection of MiniApp resource packages, and the content and structure of the packages are defined in the packaging specification.
2.2
Example 2: Access a MiniApp package in a development environment
The User agent can provide debugging tools for developers to place the MiniApp package in the user agent development environment. Developers can obtain the unique id and version number of the MiniApp in the development environment, such as "foo; version = 1.0.1". Developers can concatenate it into a MiniApp URI that opens the MiniApp:
When the user agent dereferences the URI, it obtains the MiniApp package with the specific identification "foo; version = 1.0.1" in a certain way, and then opens and runs the MiniApp.
The user agent of MiniApp corresponds to the native client implementing this specification. The user agent can parse the MiniApp URI protocol according to the rules of this specification, and it can also point to a certain resource of the unique and correct MiniApp package based on the MiniApp URI.
4.
Syntax
The MiniApp URI syntax is defined using [ABNF], using host, path-abempty, query, fragment, and unreserved from [RFC3986].
miniappuri = uri-prefix uri-infix "/" identify path-abempty ["?" query ] ["#" fragment ]
uri-prefix = (custom-scheme "://") / ("https://" host "/")
custom-scheme = 1*unreserved
uri-infix = "miniapp"identify = id [";version=" version]
id = 1*unreserved
version = *unreserved
The following are the MiniApp URI examples that conform to this syntax rule:
The strings of the MiniApp URI scheme must conform to the character set rules of the URI declared in [RFC3986].
4.1 Custom-scheme
custom-scheme is a MiniApp platform identifier to uniquely identify a user agent on a mobile device, usually registered in the operating system (say mobile deep linking technology)
uri-prefix is required, either custom-scheme or https.
the semantic and syntactic rules for custom-scheme are the same as the scheme in [RFC3986], but the custom scheme does not need to be registered in IANA. The user agent should ensure that it is unique in the device.
4.2 Id
id is the logical identifier of the MiniApp under a specific host, which along with version, points to the unique MiniApp package of a host. There may be multiple versions of a MiniApp corresponding to an id under a specific host.
id is a mandatory field.
id consists of non-reserved characters and is not case-sensitive.
The package provider that the user agent depends on must guarantee the uniqueness of the id.
4.3 Version
version and id together represent the unique MiniApp package of the user agent.
version is optional; the user agent can define rules to provide information such as version and development method.
version consists of non-reserved characters and is not case-sensitive.
In most usage scenarios, it is recommended that the version is not defined and the user agent and package provider manage versioning.
4.4
Host
The semantic rules for the host and port are consistent with the host in [RFC3986] and the port in [RFC3986].
host has nothing to do with how and where the MiniApp packages are downloaded.
4.5 Path
Path (optional) represents the path of the MiniApp resource to be opened. The packaging specification defines the resource form, how to locate a specific resource path in the package through path, and handling of the user agent when the path value is null or the referred path does not exist.
The semantic rules of path are consistent with the path in [RFC3986].
4.6
Query and fragment
See [RFC3986] for definitions of query and fragment.
5.
Dereferencing
This section describes how the user agent obtains the corresponding MiniApp package based on MiniApp URI, as well as some error handling.
The rules for dereferencing are as follows:
The OS recognizes the MiniApp URI and distributes it to the specified user agent based on the uri-prefix of the URI
The user agent recognizes MiniApp URI. If the uri-infix of this URI is miniapp, the user agent considers it as a MiniApp URI and parses the syntax components according to the syntax rules specified in this specification.
The user agent parses the syntax components of MiniApp URI according to the above syntax rules into id, version, path, query, and fragment. If the syntax parsing fails, the user agent terminates this dereferencing algorithm.
A user agent usually has two or more ways to get the MiniApp package specified by id, either from the local file path or a remote downloading package server that provides package download service.
The user agent will give priority to the local path, and if it does not find it, it will fetch it from the remote package server.
The download process using HTTPS protocol as a download protocol is described in 6.
Use HTTPS As a Network Protocol to Download MiniApp Packages below.
User agents can also provide other custom ways to get the MiniApp package.
The user agent uses id as a MiniApp logic identifier for package provider. A MiniApp identified by an id may have multiple versions in the package provider.
The user agent uses version as the version information of the MiniApp package with the specified id. The user agent handles different existence modes of the version. For example:
When version has a value, the version is used as the version information of the MiniApp package, which along with id, points to the unique MiniApp package of a package provider.
When version is not defined, the MiniApp package with a specified id is customized as a MiniApp package provider (package server or user agent), which can be the latest version or the default version of the MiniApp package with specified id, or the MiniApp package of a version that conforms to a mapping rule.
In most usage scenarios, it is recommended that the version is not defined, and the version is managed by the user agent and package provider.
The user agent obtains the MiniApp package based on the parsed provider information and the identification information of the MiniApp (e.g., id, version). The user agent handles different situations of the provider:
When provider is a package server, the user agent sends an HTTPS Request with MiniApp identification information to the server; the final MiniApp package is obtained by handling the Response body returned by the package server.
When provider is a custom method of the user agent, the user agent obtains the MiniApp package with specified MiniApp identification information through the custom method.
The user agent conducts corresponding processing based on the results of the obtained MiniApp package:
The following process is performed when the MiniApp package is obtained successfully.
When obtaining the MiniApp package fails, exception handling is performed based on the cause of failure. For example, when the user agent cannot obtain the package from the host, the error code and error message are returned.
The user agent locates the corresponding MiniApp resource based on the path, query, fragment, and method defined in MiniApp Manifest specification.
The user agent MUST handle any failure during dereferencing and provide appropriate information prompts.
6.
Use HTTPS As a Network Protocol to Download MiniApp Packages
This section is non-normative.
This section describes a use case scenario for a network protocol that uses HTTPS protocol as a request to download the MiniApp package.
If the URI does not conform to the syntax rules of MiniApp URI, the user agent does not respond or handle exceptions.
Use the HTTPS URL to get the package with the id and version as request parameters: https://example.com/getPackage?id=foo&version=1.0.1-trial
The user agent may implement HTTP cache control; it is recommended to use gzip as the encoding scheme (HTTP accept-encoding) and send HTTPS request message.
If the received request is not an HTTPS request, an HTTP 403 forbidden response is returned, and the request is terminated.
If the received request fails to pass authentication, an HTTP 403 forbidden response is returned, and the request is terminated.
If the requested HTTP Method is not supported, an HTTP 501 Not Implemented response is returned, and the request is terminated.
Based on the query or body carried in the requested URL, a MiniApp package with id “foo”, version “1.0.1” is returned. If it is not found, an HTTP 404 Not Found response is returned.
If it is successfully found, an HTTP 200 OK response is returned, and the MiniApp package is returned as the response body in the format specified by content-type.
The user agent determines whether the request is successful based on status and continues to parse the response body when the code status is 200. A failure exception is processed when the code status is not 200.
It is recommended to use the agreed unique identification field to verify the package's integrity.
For the downloaded MiniApp package, use the package format specified in the MiniApp Packaging specification to decompress.
7.
Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
There is one class of products that can conform to this specification, and that is the user agent above.
8.
Security Considerations
The user agent needs to ensure the correctness of the URI, avoid URI tampering, and prevent phishing attacks, for example, by using the recommendations in [UTR36].
It is recommended that UA or sign signature are used to authenticate the request process on the package server side.
During the request process, it is recommended to check replay attacks using HMAC.
During the request process, it is recommended to verify package integrity by abstract comparison of md5 or sha1.
While parsing the Response by the user agent, it is recommended to protect the data package security through encryption and decryption.
When the user agent stores the package resource locally, it is necessary to ensure the storage security of the files to protect against malware attacks.
A.
Acknowledgments
The editors thank the Baidu Smart Mini Program team for reviewing this document over and over again and thank the W3C MiniApps Community Group for providing a lot of valuable advice.
