Apps.install

  • Raccourci de la révision : DOM/Apps.install
  • Titre de la révision : Apps.install
  • ID de la révision : 361613
  • Créé :
  • Créateur : tregagnon
  • Version actuelle ? Non
  • Commentaire

Contenu de la révision

{{DomRef}} {{non-standard_header}}

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 {{ domxref("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.

Source de la révision

<div>
  {{DomRef}} {{non-standard_header}}</div>
<h2 id="Summary" name="Summary">Résumé</h2>
<p>Déclenche l'installation d'une application. Pendant le processus d'installation, l'application est validée et l'utilisateur doit approuver l'installation.</p>
<p>Si une application a déjà été installé depuis le même domaine, appeler <code>install()</code> à 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.</p>
<h2 id="Syntax" name="Syntax">Syntaxe</h2>
<pre class="syntaxbox">
<code>var <em>request</em> = window.navigator.mozApps.install(<em>url</em>, <em>[receipts]</em>)</code>;</pre>
<h3 id="Parameters" name="Parameters">Paramètres</h3>
<div class="note">
  <strong>Note :</strong> Il y a actuellement (Février 2013) un bug lorsque l'on passe un chemin relatif dans le paramètre <code>url</code>. Voir {{ Bug("745928") }}.</div>
<dl>
  <dt>
    <code>url</code></dt>
  <dd>
    Une chaîne de caractères d'URL contenant l'adresse du <a href="/fr/docs/Applications/Manifeste" title="/fr/docs/Applications/Manifeste">manifeste</a> à 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 <code>/</code>).</dd>
  <dt>
    <code><strong>receipts</strong></code></dt>
  <dd>
    (facultatif) un objet <a href="/en-US/docs/JSON" title="/en-US/docs/JSON">JSON</a> contenant un tableau d'un ou plusieurs reçus.</dd>
  <dd>
    <pre>
window.navigator.mozApps.install(url, {receipts: ["receipt1", ...]})</pre>
  </dd>
  <dd>
    Si <code>receipts</code> n'est pas renseigné, il est traité comme <code>null</code>.</dd>
</dl>
<p>La fonction <code>install()</code> lève une exception si l'argument requis&nbsp; (<code>url</code>) est absent, ou si des arguments non supportés sont présent.</p>
<h2 id="Returns" name="Returns">Renvoie</h2>
<div class="note">
  <strong>Note :</strong> Il y a actuellement (Février 2013) un bug avec l'attribut <code>DOMRequest.result</code> affectant les appareils Android et les ordinateurs. Voir {{ Bug("806597") }}.</div>
<p>La fonction <code>install()</code> renvoie un objet {{ domxref("DOMRequest") }}. Le champ <code>DOMRequest.result</code> contient un <a href="/fr/docs/DOM/App" title="/en-US/docs/DOM/App">objet <code>App</code></a>, qui est un objet JavaScript décrivant l'application venant d'être installée. Avant que l'opération soit finie, <code>DOMRequest.result</code> est <code>null</code>.</p>
<p>Si l'installation est infructueuse, <code>DOMRequest.error</code> contient un <a href="/en-US/docs/JavaScript_API/Error_object" title="/en-US/docs/JavaScript_API/Error_object">objet <code>DOMError</code></a>, qui a les informations à propos de l'erreur.</p>
<h2 id="Example" name="Example">Exemple</h2>
<p>Un exemple montrant comment utiliser <code>install()</code> avec les propriétés de callback <code>DOMRequest.onsuccess</code> et <code>DOMRequest.onerror</code>.</p>
<pre class="brush: js">
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);
};
</pre>
<p>Le callback <code>onsuccess</code> est appelé si l'installation est réussie. Ceci veut dire que les <a href="/fr/docs/Applications/Détails_spécifiques_à_la_plateforme" title="/fr/docs/Applications/Détails_spécifiques_à_la_plateforme">actions de l'installation</a> ont eu lieu.</p>
<p>Si l'installation est un échec, le callback <code>onerror</code> est appelé. Sur une installation échouée, <code>DOMRequest.error </code>contient un objet <code>DOMError </code>qui a des informations sur l'erreur.</p>
<p>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 <code>DOMRequest</code> 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 <code>install()</code> marche aussi par elle-même sans les guetteurs d'évènement<code>.onsuccess</code> et <code>.onerror</code>.</p>
<h2 id="Error" name="Error">Erreurs</h2>
<p>Quand l'installation est un échec, l'une de ces erreurs peut être retournée dans <code>DOMRequest.error</code>.</p>
<dl>
  <dt>
    <code>DENIED</code></dt>
  <dd>
    L'utilisateur a annulé l'installation.</dd>
  <dt>
    <code>INVALID_MANIFEST</code></dt>
  <dd>
    Le manifeste, bien qu'étant un JSON correctement formé, n'a pas certains champs requis, ou est pour une raison quelconque non valide.</dd>
  <dt>
    <code>MANIFEST_URL_ERROR</code></dt>
  <dd>
    Un autre code HTTP que le code statut 200 a été reçu, ou une autre erreur de connection.</dd>
  <dt>
    <code>MANIFEST_PARSE_ERROR</code></dt>
  <dd>
    JSON mal formé pour le manifeste.</dd>
  <dt>
    <code>NETWORK_ERROR</code></dt>
  <dd>
    Erreur de connection.</dd>
</dl>
<h2 id="Related_topics" name="Related_topics">Sujets en relation</h2>
<ul>
  <li><a href="/fr/docs/Applications/Détails_spécifiques_à_la_plateforme">Détails spécifiques à la plateforme lors de l'installation d'une Application</a></li>
  <li><a href="/fr/docs/DOM/App"><code>App</code> object</a></li>
  <li><a href="/fr/docs/DOM/DOMError"><code>DOMError</code> object</a></li>
  <li><a href="/en-US/docs/Apps/Apps_JavaScript_API">Apps JavaScript API</a></li>
</ul>
Revenir à cette révision