Apps.install

Non standard
Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

Résumé

Déclenche l'installation d'une application. Pendant le processus d'installation, l'application est validée et l'utilisateur doit approuver l'installation.

Si une application a déjà été installé depuis le même domaine, appeler install() à nouveau peux écraser silencieusement, les données déjà installées. Ceci peut être utilisé pour modifier le reçu d'achat, par exemple, quand un utilisateur passe d'une application gratuite à une application premium.

Syntaxe

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

Paramètres

Note : Il y a actuellement (Février 2013) un bug lorsque l'on passe un chemin relatif dans le paramètre url. Voir bug 745928.

url

Une chaîne de caractères d'URL contenant l'adresse du manifeste à installer. Dans le cas d'une distribution personnel (quand l'origine d'installation est la même que celle de l'application), le site peut omettre l'origine dans l'URL et fournir un chemin absolu (commençant par /).

receipts

(facultatif) un objet JSON contenant un tableau d'un ou plusieurs reçus.

window.navigator.mozApps.install(url, {receipts: ["receipt1", ...]})

Si receipts n'est pas renseigné, il est traité comme null.

La fonction install() lève une exception si l'argument requis (url) est absent, ou si des arguments non supportés sont présent.

Renvoie

Note : Il y a actuellement (Février 2013) un bug avec l'attribut DOMRequest.result affectant les appareils Android et les ordinateurs. Voir bug 806597.

La fonction install() renvoie un objet DOMRequest. Le champ DOMRequest.result contient un objet App, qui est un objet JavaScript décrivant l'application venant d'être installée. Avant que l'opération soit finie, DOMRequest.result est null.

Si l'installation est infructueuse, DOMRequest.error contient un objet DOMError, qui a les informations à propos de l'erreur.

Exemple

Un exemple montrant comment utiliser install() avec les propriétés de callback DOMRequest.onsuccess et DOMRequest.onerror.

var request = window.navigator.mozApps.install(manifestUrl);
request.onsuccess = function () {
  // Enregistre l'objet App qui est renvoyé
  var appRecord = this.result;
  alert('Installation réussie !');
};
request.onerror = function () {
  // Affiche le nom de l'erreur depuis l'objet DOMError
  alert('Installation échouée, erreur : ' + this.error.name);
};

Le callback onsuccess est appelé si l'installation est réussie. Ceci veut dire que les actions de l'installation ont eu lieu.

Si l'installation est un échec, le callback onerror est appelé. Sur une installation échouée, DOMRequest.error contient un objet DOMError qui a des informations sur l'erreur.

Le code peut vous apparaître étrange, avec les guetteurs d'évènement ajoutés après que la fonction ait été appelée. Cependant, c'est la façon dont l'objet DOMRequest opère. L'appel de la fonction attendra que les guetteurs d'évènement aient été définis, et ils seront déclenchés en fonction de la situation. La fonction install() marche aussi par elle-même sans les guetteurs d'évènement.onsuccess et .onerror.

Erreurs

Quand l'installation est un échec, l'une de ces erreurs peut être retournée dans DOMRequest.error.

DENIED: L'utilisateur a annulé l'installation.
INVALID_MANIFEST: Le manifeste, bien qu'étant un JSON correctement formé, n'a pas certains champs requis, ou est pour une raison quelconque non valide.
MANIFEST_URL_ERROR: Un autre code HTTP que le code statut 200 a été reçu, ou une autre erreur de connection.
MANIFEST_PARSE_ERROR: JSON mal formé pour le manifeste.
NETWORK_ERROR: Erreur de connection.