DOMApplicationsRegistry.install()
Marketplace feature removal
The functionality described on this page no longer works — Firefox Marketplace has discontinued support for Android, Desktop, Tablets, and payments (and other related functionality). For more information, read the Future of Marketplace FAQ.
Summary
Triggers the installation of an app. During the installation process, the app is validated and the user is prompted to approve the installation.
If the app has previously been installed from the same domain, calling install()
again may silently overwrite the existing install data. This can be used to modify the purchase receipt, for example, when a user upgrades from a free app to a premium app.
Syntax
<code>var request = window.navigator.mozApps.install(url, [receipt1, …])</code>;
Parameters
url
parameter. See bug 745928.url
- A
string
URL containing the location of the manifest to be installed. In the case of self distribution (where the installing origin is the same as the app origin), the installing site may omit the origin part of the URL and provide an absolute path (beginning with/
). receipts
- (Optional) An array of one or more receipts. Example:
-
JavaScriptCopy Code
window.navigator.mozApps.install(url, ["receipt"])
- If
receipts
is omitted it is treated asnull
. For more information see Validating a receipt.
The install()
function throws an exception if the required argument (url
) is missing, or if unsupported arguments are present.
Return value
The install()
function returns a DOMRequest
object. The DOMRequest.result
field contains a DOMApplication
object, which is a JavaScript object that describes the app that was just installed. Before the operation is finished, DOMRequest.result
is null
.
If the installation is not successful, DOMRequest.error
contains a DOMError
object, which has information about the error.
Errors
When the installation is unsuccessful, one of the following errors can be returned in DOMRequest.error
.
DENIED
- The user cancelled the installation.
INVALID_MANIFEST
- The manifest, while well-formed JSON, does not have some required field or is somehow invalid.
MANIFEST_URL_ERROR
- Something other than an HTTP 200 status code was received, or some connection errors.
INVALID_URL
MANIFEST_PARSE_ERROR
- Bad JSON in the manifest.
NETWORK_ERROR
- Connection error.
REINSTALL_FORBIDDEN
- Reinstalls of apps are forbidden.
MULTIPLE_APPS_PER_ORIGIN_FORBIDDEN
- Prior to Gecko 34 (Firefox OS before 2.2, Firefox Desktop/Android before 34), installable apps have a "single app per origin" security policy; basically, you can't host more than one installable app per origin.
Example
An example that shows how to use install()
with the DOMRequest.onsuccess
and DOMRequest.onerror
callback properties.
var request = window.navigator.mozApps.install(manifestUrl); request.onsuccess = function () { // Save the App object that is returned var appRecord = this.result; alert('Installation successful!'); }; request.onerror = function () { // Display the error information from the DOMError object alert('Install failed, error: ' + this.error.name); };
The onsuccess
callback is called if the installation is successful. This means that the installation actions described here have occurred.
If the installation is not successful the onerror
callback is called. On a failed installation, DOMRequest.error
contains a DOMError
object that has information about the error.
The code above may look unusual to you, with listeners being added after the function has already been invoked. However, this is the way the DOMRequest
object operates. The function invocation will wait until the listeners are defined, and then the listeners will fire appropriately. The install()
function also works by itself, without the .onsuccess
and .onerror
listeners.
Related topics
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/apps/install