Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document specifies two classes of Web application: hosted Web applications and packaged applications. These applications differ from traditional Web applications in their life cycle, security model, and access to APIs that are not normally available to Web applications. Conceptually, the application manifest indicates that an application can be "installed" on an end-user's device. What distinguishes a traditional Web application from a hosted web application is an application manifest: this is a JSON resource that contains application specific metadata (e.g., the name of the application), and optionally various security related permission requests to resources on the Web and/or services and capabilities on the device.
Installation of hosted or packaged applications onto a device can be
initiated through either linking to an application manifest or through
the use of the ApplicationRegistry
API. This API gives a
developer a degree of control over the installation process.
This specification also specifies aspects related to the application's lifecycle that are outside the control of the developer. These events sometimes result in system messages being generated. Developers can register event listeners to listen for these special events during the life cycle of their application.
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.
The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
There is only one class of product that can claim conformance to this specification: a user agent.
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL].
The EventHandler interface represents a callback used for event handlers as defined in [HTML5].
The concept of fire a simple event is defined in [HTML5].
The terms event handlers and event handler event types are defined in [HTML5].
The DOMError interface represents an error handling object as defined in [DOM4].
ApplicationManagement
interface is defined in the
Privileged Applications Extensions
specification.
Web Applications are represented by the Application interface.
install()
in
ApplicationRegistry.
error
event to
the DOMRequest object with the
"NotAllowedError"
error code and exit those steps.
success
event to the DOMRequest
object and set result
to null.error
event to
the DOMRequest object with an error code that
describes the error.
error
event to the DOMRequest
object with the "NotInstalledError"
error code and
exit those steps.
error
event to
the DOMRequest object with the
"NotAllowedError"
error code and exit those steps.
success
event to the
DOMRequest object and set result
to
null.error
event to
the DOMRequest object with an error code that
describes the error.
available
, downloading
,
downloaded
or installing
, depending on
the state of the application.installing
.downloaded
.downloading
.available
. Otherwise, the attribute MUST
return the empty string.
InvalidState
and abort these steps.
running
if the current
application state is running. Otherwise, if the current
application state is paused, it MUST return
paused
. Otherwise, it MUST return
terminated
.
The following are the event handlers (and their corresponding
event handler event types) that MUST be supported as
attributes by the Application
objects:
event handler | event handler event type |
---|---|
onlaunch
|
launch
|
onpause
|
pause
|
onresume
|
resume
|
onterminate
|
terminate
|
UserCancel
.
error
the attribute MUST
return 0.0. Otherwise, if the current state is
success
, the attribute MUST return 1.0. Otherwise,
the attribute SHOULD return the current progress of the download
expressed between 0.0 and 1.0.
When the caller start the download, the DownloadRequest SHOULD start downloading the resource.
If the resource fails to download, the UA MUST send an error
message to the request.
If the resource succeed to download, the UA MUST send a success message to the request.
While the resource is downloading, which means as long as
readyState
is pending
, the UA SHOULD
regularly fire a simple event named progress on the
object. The UA should note that sending too much events might have
an impact on performance but sending too few of them might impact
the user experience.
The following are the event handlers (and their
corresponding event handler event types) that MUST be
supported as attributes by the DOMRequest
objects:
event handler | event handler event type |
---|---|
onprogress
|
progress
|
An ApplicationRegistry instance is exposed on the
Navigator
object trough the an app
attribute.
The ApplicationRegistry interface allows handling applications and query there status.
error
event to
the DOMRequest object with the
"NotAllowedError"
error code and exit those steps.
manifestUrl
.
success
event to the DOMRequest
object and set result
to null.error
event to
the DOMRequest object with an error code that
describes the error.
The UA SHOULD verify at any moment before installing that
manifestUrl
points to a valid manifest. If this is
not the case, the UA MUST fire an error
event to
the DOMRequest object with the
"InvalidArgumentError"
and exit the steps.
The UA SHOULD save the parameters
if some are
passed so they can later be retrieved by the
parameters
attribute on the Application
interface.
success
event to the DOMRequest object and sets its
result
attribute to the Application object
representing the current context or null
if the
current context is not an application context.
success
event to the DOMRequest object and
populate its result
attribute with an array of
Application objects representing the applications.
success
event to the DOMRequest object and
populate its result
attribute with the boolean value
true if there is an installed application fulfilling the
condition, otherwise result
should be set to false.
A packaged application is an application that is self-contained in a container. All resources that are commonly used by the application SHOULD be available in the container.
A hosted application is an application that is not a packaged application.
A packaged application would be useful in a few situations, amongst them:
An application manifest for the application MUST be present at the root of the container.
The container of a packaged application MUST be a ZIP file.
The origin of each instance of a packaged application MUST be
universally unique for the life of that application (i.e., until it
is uninstalled) [ORIGIN]. As such, it is RECOMMENDED that a user
agent synthesize an origin for a packaged application using the
app:
URI scheme [APP-URI]. Relative URLs to resources
within the packaged application can then be dereferenced using the
dereferencing rules specified in the [APP-URI] specification.
Inside a packaged application, the valid application manifest
filename is manifest.webapp
.
A packaged application MUST have a copy of its application manifest outside of the package so it can be used for installation and updates purposes. As a consequence, that copy of the application manifest can be reduced to only a few properties: name, version and relNotes. In addition, a new property can be used only in the content a packaged application manifest: package that SHOULD contain an object with the following properties:
{ "name": "My Packaged App", "description": "This is my first packaged app!", "launch_path": "/", "version": "1.0", "developer": { "name": "Mozilla", "url": "https://mozilla.org/en-US" }, "package": { "url": "http://example.org/mypackagedapp.zip", "size": "1024", "sha256": "6df134b0cfd88d6d4f27a99e29b9923d50eb8b2c0d5289c60012de424c7a9d97" } }
An application SHOULD advertise an update by updating its application manifest.
The UA SHOULD regularly check if the application manifest of installed applications has not been updated. To know if the file has been updated, HTTP semantics apply.
For package applications, both application manifests (outside and inside the package) SHOULD be updated. However, the application manifest inside the package SHOULD always be checked to make sure the update (or the install) is genuine.
In the context of a running application, all usual rules for data isolation MUST apply: same-origin policy, same-domain policy, or whatever is used. However, between two applications, those rules no longer apply. Two applications MUST be fully isolated from each other in the sense that they SHOULD NOT be able to access data from each other. For example, if App1 accesses http://example.org and gets a cookie from it, App2 should not be able to see that cookie when accessing http://example.org even if the usual cookie sharing policy should allow this to happen.
This isolation SHOULD apply for all data storage like cookies,
localStorage, IndexedDB, app cache and any other
Web Platform mechanism that allows to store data and does not
explicitly opt out from the application data isolation.
The isolation SHOULD also apply to UA specifics data storage. For
example, any permission granted or denied to a host/origin/domain
should be isolated per-application or auto-fill and auto-completion
features for forms.
Depending on the user interface around the application context, navigating outside the application's origin might lock the user out of the application. To prevent that, the UA SHOULD NOT allow navigation out of the application's origin, unless the origin is specified in the following application manifest property:
If the application tries to navigate to an unauthorized origin, the UA SHOULD open the link in a regular but distinct browsing context.
System Messages are events sent by the system to an application
which has registered for it before. Those events are different from DOM
events in the sense that they are always originated by the system and
that if the targeted application is not currently running, it will be
started.
In addition, unhandled messages will stay in a queue.
Some applications might be interested in getting some events even if
they are not running and want to be woken up if such event is sent
while they are asleep.
In addition, when the application is being woken, it needs to know as
soon as possible why it has been disturbed to be able to show the
appropriate interface.
Finally, the capability of being woken should be transparent to the
application.
The type of system message identifies a category of system
messages.
Application are able to register and handle system messages based on
their types. There is no exhaustive list of system messages type. Any
specification can create a new type of system message.
Each application has a pool of messages for each type
of system message. Every time a system message is sent to an
application, if there is no handler for that message's type, the UA
MUST add the message to the pool of messages used for that type.
The UA MAY, for memory optimization, discard old messages if the pool
becomes too big or if the messages are too old.
When a UA is required to fire a system message of a given type, it has to do one of these actions:
Some API might allow the application to access sensitive parts of the hardware or sensitive information. To prevent applications to access them, some APIs might require one or more permissions. For example, for an application to be allowed to access your geolocation information, it has to be granted the geolocation permission.
An application SHOULD define all permissions it is going to use in the application manifest. The UA MAY automatically grant some permissions at install-time or ask the user to grant some applications. However, MAY, in addition or alternatively, ask the user to grant permissions at run-time.
The user MUST be able to revoke a granted permission or grant a denied permission at any time.
Specifications are expected to declare the permissions they will require for their feature to work. Altough, some basic permissions can't really go into a specific specification or a related to specifications that might be harder to change.
Thus, this specification defines the following permissions:
Permission Name | Permission Description | Access Type |
---|---|---|
notification
|
Allow the application to use the Web Notifications API. | N/A |
geolocation
|
Allow the application to access the Geolocation API. | N/A |
storage
|
Allow localStorage and IndexedDB without size limitations. | N/A |
webapps-manage
|
Allow access to the navigator.apps.management API to
manage installed webapps.
|
N/A |
At any time, an application MUST be in one of the following states: running, paused, terminated.
An application is running when it has been launched by the UA and has not been put in paused. A running application can transition to paused or terminated states.
If a running application transitions to a paused state,
the UA MUST fire a simple event named pause
on
the Application object before switching its state.
If a running application transitions to a terminated
state, the UA MUST fire a simple event named
terminate
on the Application object before
shutting down the application.
An application is paused when the UA stops the execution of an application without terminating it. A paused application SHOULD have all its scripts no longer running, such as rendering, parsing, processing media files and any action that requires CPU and memory or would distract the user. A paused application can transition to running or terminated states.
If a paused application transitions to a running state,
the UA MUST fire a simple event named resume
on
the Application object after changing its state.
An application is terminated when the application has been stopped and is no longer loaded in the system. The state of a terminated application can only be changed to running if the application is launched again.
If a terminated application transitions to a running
state, the UA MUST fire a simple event named
launch
on the Application object after the main
browsing context is created but before the load
and
DOMContentLoaded
events are fired.
The specification currently assumes that one will save important when paused so there is no terminate event when transitioning from pause to terminate.
Do we have real use cases for launch
?
Is firing before load
a hard thing to do?
While an application is running, it can be part or fully hidden. The visibility events described in [PAGE-VISIBILITY] MUST be sent when the visibility status of the application changes.
In addition, when the application becomes fully hidden, the UA MAY put the application in a paused state.
The DOMRequest interface is temporarily hosted by this specification. The Runtime and Security Model for Web Applications specificaton does not plan to keep that guest for ever, this is why it is currently staying in an appendix.
Some methods want to return a value or do an action but can't do it
synchronously, most of the time for performance reasons. In that
case, most of those methods will use a callback mechanism to inform
the caller of the success or the failure of the action.
However, this callback mechanism makes the code barely readable and
there is no common pattern used by all API in the Web Platform.
DOMRequest intend to be used instead of those callbacks to
make those APIs more developer-friendly and help code readability.
The DOMRequest interface is intended to be used by asynchronous methods that want to return something after performing an action or simply want to inform the caller that the action is done. It returned request can also be used to inform that an error happened during the operation.
A DOMRequest has three state. It is whether
pending
, success
or error
.
The initial state of a DOMRequest MUST be
pending
.
If a DOMRequest receives a success message while in the
pending
state, its state MUST change to
success
and SHOULD NOT change afterward.
If a DOMRequest receives an error message while in the
pending
state, its state MUST change to
error
and SHOULD NOT change afterward.
If a DOMRequest receives a success message or an
error message while not in the pending
state, the
message MUST be ignored.
A success message SHOULD be sent to the DOMRequest
when the operation is successfully terminated. The message MAY
contain a value which MUST be used by the result
attribute. If the message does not contain a value, null MUST
be used instead.
As soon as a success message is received,
readyState
MUST return done
,
result
MUST return the received value or null as
explained above and the object MUST NOT change its state and MUST,
therefore, ignore all following success message and error
message.
Finally, the UA MUST fire a simple event named
success
on the object
An error message SHOULD be sent to the DOMRequest
when the operation has failed. The message MAY contain a value which
MUST be a DOMError object and MUST be used by the
error
attribute. If the message does not contain a
value, the UA SHOULD find the most appropriate DOMError that
represents the failure.
As soon as an error message is received,
readyState
MUST return done
,
error
MUST return the received value the most
appropriate error value as explained above and the object MUST NOT
change its state and MUST, therefore, ignore all following success
message and error message.
Finally, the UA MUST fire a simple event named
error
on the object.
pending
if the current
state is pending
. Otherwise, it MUST return
done
.
undefined
if the current
state is not success
. Otherwise, it MUST return the
value provided by the success message or null
if no value was sent with the message.
error
. Otherwise, it MUST return the value provided
by by the error message. If there was no provided value,
it SHOULD return the most appropriate DOMError that
represents the failure.
The following are the event handlers (and their
corresponding event handler event types) that MUST be
supported as attributes by the DOMRequest
objects:
event handler | event handler event type |
---|---|
onerror
|
error
|
onsuccess
|
success
|
Special thanks to the Mozilla team working on Open Web Apps, especially Anant Narayanan for his Web Application Manifest Format and Management APIs specification that this document reuse shamelessly and Fabrice Desré for his help in understanding why some decisions were made.
Special thanks to the Samsung team, especially 金明(Ming Jin), Janusz Majnert and 송정기(Jungkee Song) for their work on the System Application Runtime: Execution and Security Model specification.
Special thanks to Jonas Sicking and Marcos Caceres for their invaluable help.
Thanks to John Lyle, Christophe Dumez and Jonathan Jeon for their useful comments and change proposals.