navigator.mozApps.install Redirect 1

« DOM Reference

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

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

var request = window.navigator.mozApps.install(url, [receipt1, …]);

Parameters

Note: There is currently (May 2012) a bug with passing a relative path in the 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:
window.navigator.mozApps.install(url, ["receipt"])
If receipts is omitted it is treated as null. 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.

Returns

Note: There is currently (Jan 2013) a bug with DOMRequest.result attribute that affects to desktop and Android devices. See bug 806597.

The install() function returns a DOMRequest object. The DOMRequest.result field contains an App 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.

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.

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.
MANIFEST_PARSE_ERROR
Bad JSON in the manifest.
NETWORK_ERROR
Connection error.
REINSTALL_FORBIDDEN
Reinstalls of apps are forbidden.
MULTIPLE_APPS_PER_ORIGIN_FORBIDDEN
Installable apps have a "single app per origin" security policy; basically, you can't host more than one installable app per origin.

Document Tags and Contributors

Last updated by: Sheppy,