Manifeste d'application

Créer un manifeste

Dans cette section, nous allons voir les étapes nécessaires pour créer et utiliser un manifeste d'application.

Conventions : nom de fichier, emplacement et format

• Nom : mon_manifeste.webapp (il est nécessaire d'utiliser l'extension .webapp)
• Emplacement : à la racine du répertoire de l'application
• Format : JSON (le JSON du manifeste doit être valide

Gestion des chemins

• Les chemins utilisés de façon interne pour les manifestes, les icônes et autres doivent être absolus à partir de l'origine de l'application et non depuis la racine de l'application. Par exemple, si votre manifeste se situe à l'URL : https://www.monsite.com/monapp/manifest.webapp, le chemin d'installation sera /monapp/manifest.webapp et pas /manifest.webapp.
• Les chemins internes doivent être services depuis la même origine que l'application
• Les chemins externes doivent être entièrement qualifiés. Par exemple, avec une application empaquetée sur le Firefox Marketplace qui utilise une icône sur un serveur distant, le chemin à utiliser pour l'icône serait : https://monappliweb/images/icon.png.

Conditions à respecter pour envoyer une application au Firefox Marketplace

Si vous souhaitez que votre application soit publiée sur le Firefox Marketplace, le manifeste de votre application doit contenir les champs suivants :

• name
• description
• launch_path (pour les applications empaquetées)
• icons (1 icône 128x128 nécessaire, 1 icône 512x512 recommandée)
• developer
• default_locale (si locales est défini)
• type

Conditions à respecter pour un application web générique

Si vous souhaitez construire un application web, non publiée sur le Firefox Marketplace, le manifeste de votre application devra contenir les champs suivants:

• name
• description
• icons (1 icône 128x128 nécessaire, 1 icône 512x512 recommandée)

Validation d'un manifeste

Si vous soumettez votre application pour le Firefox Marketplace, le manifeste de votre application devra passer des tests de validations.

Vous pouvez utiliser le validateur d'application pour identifier d'éventuelles erreurs. Vous pouvez également utiliser cette API pour valider votre manifeste.

Mettre à jour les manifestes

Pour plus de détails sur les mises à jour des applications, voir la section à ce sujet.

-----------

Un exemple de manifeste

Le bout de code suivant est un manifeste très simple. Vous pouvez le copier dans un fichier texte et remplacer les valeurs par vos informations.

{
  "name": "Mon application",
  "description": "Une description courte de l'application",
  "launch_path": "/",
  "icons": {
    "128": "/img/icone-128.png"
  },
  "developer": {
    "name": "Votre nom ou celle de votre organisation",
    "url": "https://votre-site-web.org"
  },
  "default_locale": "fr"
}

Les champs du manifeste

Les champs suivants sont autorisés dans un manifeste. Il n'y a que deux champs requis : name et description. D'autres champs peuvent être requis si vous utilisez certains champs. Ceci sera précisé dans la documentation.

Les champs peuvent apparaître dans n'importe quel ordre. Tout champ en dehors de cette liste, sera ignoré.

activities

(Firefox OS seulement, facultatif) Renseigne un ensemble d'activités Web supportées par l'application. Chaque propriété dans ce champ est une activité. Les noms de ces activités sont des champs textes libres, et chaque activité est représenté par un objet. Voici un exemple du champ activities, avec une seule activité nommée share :

"activities": {
  "share": {
    "filters": {
      "type": [ "image/png", "image/gif" ]
    },
    "href": "foo.html",
    "disposition": "window",
    "returnValue": true
  }
}

Dans cet exemple, l'objet pour l'activité share possède trois propriétés : filters, href, et disposition. Elles sont décrites ci-dessous.

• href - (requise) Quand une autre application ou page web initie une activité qui est supportée par cette application, et si cette application est désignée pour réaliser cette activité, cette propriété indique la page qui doit être ouverte. Elle sera ouverte de la façon indiquée dans la propriété disposition.
• disposition - (facultatif) Précise comment la page indiquée dans href doit être présentée quand l'activité est invoquée. La valeur, si renseignée, doit être une des suivantes (par défaut window) :
  • window - La page prenant en charge l'activité doit être ouverte dans une nouvelle "fenêtre" (sur un appareil mobile, cette vue remplacera celle de l'application qui a demandé l'activité). Cette page doit appeler la méthode navigator.setMessageHandler pour chaque activité qu'elle supporte et exécuter l'activité pour laquelle elle a reçu le message. Ensuite, si l'activité retourne une valeur, cette page doit appeler activity.postResult ou activity.postError (où activity est le premier argument fourni à la fonction spécifiée par setMessageHandler). Ces fonctions sont détaillées dans activités Web.
  • inline - La page qui prend en charge l'activité recouvrira la page d'origine (sur un appareil mobile, elle sera rendue dans un popup au-dessus de l'application originale qui a demandé l'activité). Le comportement reste ensuite similaire à window.
• filters - (facultatif) Un dictionnaire, dont chaque propriété définit un filtre. Ces filtres sont appliqués pour déterminer les applications adaptées à la prise en charge de l'activité donnée. Les noms des filtres sont des champs texte libres, mais leurs valeurs doivent être une chaîne de caractères, ou un tableau de chaînes de caractères (le type exact dépend du filtre).

appcache_path

(facultatif) Le chemin absolu vers le manifeste de cache de l'application (AppCache). Quand une Open Web App est installée, le manifeste AppCache est récupéré et interprété, et les éléments statiques sous l'en-tête CACHE sont mis en cache.

"appcache_path": "/cache.manifest"

chrome

Nécessite Firefox OS 1.1 (facultatif) Ajoute une interface de navigation en bas de l'écran. C'est un moyen rapide d'ajouter une navigation à une application qui ne fournit pas de bouton pour revenir en arrière.

"chrome": { "navigation": true }

csp

(facultatif) Précise une Politique de sécurité (Content Security Policy) pour l'application. Cette politique s'applique à toutes les pages chargées via l'application. La syntaxe CSP est décrite sur la page https://wiki.mozilla.org/Security/CSP/Specification.

Notez bien que pour les applications certifiées et privilégiées une CSP par défaut s'applique toujours, même si vous n'utilisez pas cette propriété. Pour ces applications, si vous précisez une politique de CSP en utilisant cette propriété, les deux politiques seront fusionnées, ce qui signifie que toute action devra être autorisée à la fois par les deux politiques (par défaut et celle que vous aurez précisée dans cette propriété).

Les CSP par défaut pour les applications privilégiées et certifiées sont :

Privilégiée

"default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"

Certifiée

"default-src *; script-src 'self'; object-src 'none'; style-src 'self'"

default_locale

(requis quand locales est présent) Un identifiant de langue (RFC 4646) qui indique quel langage le manifeste utilise. Ne pas inclure dans le champ locales, l'identifiant de langue utilisé dans cette propriété. Il est préférable de toujours définir default_locale, même si vous n'utilisez pas locales. Le Firefox Marketplace l'utilisera pour savoir dans quel langue est votre manifeste, et ainsi utiliser les bonnes valeurs dans les champs traduits. Si vous ne définissez pas de default_locale, le Marketplace devra deviner la langue. default_locale n'est pas utilisé par l'appareil qui installe l'application.

Exemple pour le français :

 "default_locale": "fr"​

description

(requis) Une description de l'application (longueur maximum de 1024 caractères).

developer

(facultatif) Informations sur le développeur de l'application. Possède ces propriétés :

• name - Le nom du développeur
• url - L'URL d'un site contenant plus d'informations sur le développeur de l'application. Cette URL est habituellement chargée quand l'utilisateur clique sur le nom du développeur, en regardant le détail de l'application depuis son tableau de bord (dashboard), ou son navigateur.

fullscreen

(Firefox OS seulement, facultatif) Définir à true ou false pour indique à l’exécutable si l'application doit être lancé en plein-écran. Exemple :

"fullscreen": "true"

icons

(facultatif) Un objet contenant les tailles d'icône avec les URIs pour chaque icône correspondante (peut être un chemin absolu, relatif ou des data URIs). Les icônes doivent être carrées et pensées pour représenter l'application web. Les chemins commençant par / sont traités comme des chemins relatifs depuis la racine de l'application.

Pour Windows 7 et Android, les tailles d'icônes suivantes sont supportées :

• 16 × 16
• 32 × 32
• 48 × 48
• 64 × 64
• 128 × 128
• 256 × 256

Pour Firefox OS, les icônes ne doivent pas projeter d'ombre et doivent remplir toute la surface de l'icône, dans les tailles suivantes :

• 30 × 30
• 60 × 60

Vous pouvez lire les recommandations sur le design d'icônes pour Firefox OS.

Vous pouvez renseigner plusieurs icônes en suivant cet exemple :

"icons": {
  "16": "/img/icon-16.png",
  "48": "/img/icon-48.png",
  "128": "/img/icon-128.png"
}

installs_allowed_from

(facultatif) Un tableau des origines (schéma + domaine, par exemple https://marketplace.exemple.com) qui sont autorisés à déclencher l'installation de l'application. Ce champ vous permet de n'autoriser l'installation que pour certains sites ou boutiques, avec lesquels vous avez des partenariats. Le tableau ["*"] indique que l'installation de l'application est autorisée depuis n'importe quel site. Il s'agit de la valeur par défaut. Notez que [] désactiverait l'installation depuis tout site, le votre inclus. Voici un exemple autorisant l'installation depuis n'importe quel site :

"installs_allowed_from": ["*"]

launch_path

(facultatif, requis pour les applications empaquetées) Le chemin chargé quand l'application démarre. Si il n'est pas fourni, l'origine de l'application sera pris en compte. Voir Gestion des chemins.

Dans une application empaquetée (packaged app), ce champ spécifie le point de départ du contenu local du fichier zip contenant l'application. Par exemple, si launch_path a pour valeur /monApp/index.html, alors l'application empaquetée sera lancée en ouvrant le fichier /monApp/index.html.

locales

(facultatif) Un objet de surcharges des données contenues dans le manifeste, pour chaque langue définie. L'interface (UI) utilisera ces informations pour traduire les écrans en fonctions des paramètres de l'appareil. Par exemple, si des personnes parlant italiens installent votre application, vous souhaiterez sûrement afficher les textes de l'interface en Italien. Chaque entrée pour une langue est définie par un identifiant de langue (RFC 4646) et contient une représentation simplifiée du manifeste. Tout champ présent dans la propriété locales écrase le champ correspondant dans le manifeste. Vous ne pouvez pas écraser les champs : default_locale, locales, et installs_allowed_from. Un manifeste qui écrase n'importe lequel de ces champs est non valide. Quand locales est présent, default_locale doit l'être aussi

Exemple avec l'Espagnol et l'Italien :

"locales": {
  "es": {
    "description": "¡Acción abierta emocionante del desarrollo del Web!",
    "developer": {
      "url": "https://es.mozillalabs.com/"
    }
  },
  "it": {
    "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
    "developer": {
      "url": "https://it.mozillalabs.com/"
    }
  }
}

messages

(Firefox OS seulement, facultatif) Indique les messages système que l'application peut capturer. Il s'agit d'un tableau indiquant la correspondance entre les messages système et les pages qui s'afficheront lorsque le message aura lieu. Exemple pour une application Firefox OS :

"messages": [
  { "telephony-new-call": "/dialer/index.html#keyboard-view" },
  { "bluetooth-dialer-command": "/dialer/index.html#keyboard-view" },
  { "headset-button": "/dialer/index.html#keyboard-view" },
  { "notification": "/dialer/index.html#keyboard-view" },
  { "alarm": "/facebook/fb_sync.html" }
]

Dans cette exemple, quand un message système telephony-new-call a lieu (indiquant un appel entrant), l'appareil affiche la page /dialer/index.html, au niveau de l'ancre #keyboard-view. Cette page doit faire quelque chose comme donner à l'utilisateur des informations sur l'appel et lui offrir le moyen de répondre à l'appel.

name

(requis) Le nom de l'application (longueur maximum de 128 caractères).

orientation

(Android et Firefox OS seulement, facultatif) Un tableau définissant les orientations dans lesquelles l'application doit rester verrouiller, même si l'orientation de l'appareil change. Chaque entrée dans le tableau peut être un des éléments de cette liste : portrait, landscape, portrait-primary, landscape-primary, portrait-secondary ou landscape-secondary. Les options avec primary ou secondary verrouillent l'orientation dans une seule orientation de l'appareil, même si cette orientation change. Les options sans primary et secondary combinent les règles avec primary et secondary. Les options suffixées par -secondary implique une orientation à 180 degrés par rapport à l'option sans suffixe. Par exemple, tenir le téléphone la tête en bas (mais toujours de façon à ce que la largeur soit inférieure à la hauteur), implique l'orientation portrait-secondary. Si ce champ a une valeur valide, l’exécutable ne changera pas l'orientation de la vue rendant l'application même si l'appareil est tourné. Exemple :

"orientation": ["portrait","landscape-secondary"]

origin

Nécessite Firefox OS 1.1 (applications privilégiées ou certifiées seulement) Utilisé pour donner une origine à une application privilégiée ou certifiée. Vous n'avez pas besoin de ce champ pour les applications hebergées, qui ont déjà une origine (le site web qui les sert). Ce champs est utilisable pour rendre plus s'imple une identification de type OAuth ou Persona pour une application empaquetée (packaged app).

Il y a un protocol spécial au sein d'une application empaquetée, qui est app://<UUID> où <UUID> est une longue chaîne de caractère qui est unique à chaque appareil où l'application est installée. Cette URL est difficilement accessible au développeur d'applications pour le moment. Le champ origin vous permet de remplacer le UUID par simple nom de domaine qui sera utilisé à chaque installation de l'application, par exemple app://mon-app.com.

Vous devez contrôler le nom de domaine que vous utilisez dans ce champ. L'application ne sera pas acceptée dans le Firefox Marketplace si son origin est app://facebook.com et que vous n'êtes pas Facebook.

Exemple (n'oubliez pas le protocol app://) :

"origin": "app://mon-app.com"

permissions

(facultatif) L'ensemble des permissions dont l'application a besoin. Une application doit lister toutes les API qu'elles comptent utiliser qui nécessitent l'autorisation de l'utilisateur. Si une application essaye d'utiliser une de ces APIs sans avoir l'entrée correspondante dans ce champ, elle échouera.

Le champ permissions est un objet, chaque propriété indiquant une seule permission. Chaque entrée d'API doit avoir une propriété description. Certaines APIs nécessitent aussi une propriété access. Exemple du champ permissions :

"permissions": {
  "contacts": {
    "description": "Nécessaire pour l'aide à la saisie dans l'écran de partage",
    "access": "readcreate"
  },
  "alarms": {
    "description": "Nécessaire pour programmer des notifications"
  }
}

• description - Une chaîne indiquant l'intention derrière la demande pour utiliser cette API. Ce champ est obligatoire.
• access - Une chaîne de caractères indiquant le type d'accès requis pour la permission. Cette propriété n'est nécessaire que pour un petit nombre d'APIs. Les valeurs possibles sont read, readwrite, readcreate, et createonly.

Les APIs de permissions sont listées ci-dessous. Si une API requiert une propriété access, c'est précisé. Pour plus d'informations sur où ces permissions sont pris en charge, voir Permissions d'application.

• alarms - Programmer une notification, ou programmer le démarrage d'une application.
• browser - Permettre d'implémenter un navigateur.
• contacts - Ajouter, lire ou modifier des contacts depuis le carnet d'adresses sur l'appareil et lire les contacts depuis la carte SIM. Propriété access requise : une valeur parmi readonly, readwrite, readcreate, ou createonly.
• device-storage:music/device-storage:videos/device-storage:pictures/device-storage:sdcard - Ajouter, lire ou modifier des fichiers stockés sur l'appareil. Propriété access requise : une valeur parmi readonly, readwrite, readcreate, ou createonly.
• fmradio - Contrôller la radio FM.
• geolocation - Obtenir la position actuelle de l'utilisateur.
• storage - Utiliser localStorage ou IndexedDB sans restriction de taille.
• systemXHR - Créer des requêtes HTTP sans aucune restriction sur l'origine.
• tcp-socket - Créer et communiquer par des sockets TCP.
• wifi-manage - Énumérer les réseaux Wifi disponibles, obtenir la force du signal, connecter à un réseau.

Il y a d'autres propriétés qui ne sont accessibles que pour les applications certifiées :

• backgroundservice - Permettre à une application web de tourner en tâche de fond et de réaliser des tâches comme de la synchronisation ou répondre à des messages entrants.
• bluetooth - Accès bas niveau au matériel Bluetooth.
• camera - Prendre des photos, filmer des vidéos et contrôler l'appareil photo. La raison pour que cette API ne soit limitée qu'aux applications certifiées, est que le bac à sable (sandbox) pour les applications, empêche l'accès au matériel de la camera. Notre but est de la rendre accessible aux applications tierces dès que possible, mais nous n'aurons pas le temps de le faire pour la sortie initiale.
• desktop-notification - Afficher une notification sur le bureau de l'utilisateur.
• mobileconnection - Obtenir des informations sur les connections mobiles actuelles Voix et Data.
• power - Allumer ou éteindre l'affichage, contrôler le CPU, l'alimentation de l'appareil, et ainsi de suite. Écouter et inspecter des évènements de verrouillage de ressource.
• settings - Configurer et lire les paramètres de l'appareil. Propriété access requise : une valeur parmi readonly ou readwrite.
• sms - Envoyer et recevoir des SMS.
• telephony - Accéder à toutes les APIs téléphone.
• webapps-manage - Obtenir accès à l'API navigator.mozApps.mgmt qui gère les Open Web Apps installées.
• time - (anciennement systemclock) Définir l'heure actuelle. (Le fuseau horaire est contrôlé par l'API settings).

type

(facultatif) Le type de l'application, peut être web, privileged, ou certified. Ces types sont décrits ci-dessous.

• web - Une application normale. Les permissions sont limitées à celles contenues dans la première liste de permissions de cette page. Si vous ne remplissez pas de champ type dans le manifeste, web sera la valeur par défaut.
• privileged - Une Open Web App authentifiée qui a été approuvée par une boutique d'applications telle que le Firefox Marketplace. Certaines APIs de sécurité ou d'accès à des informations privées, ne sont accessibles que pour les applications privilégiées, ceci afin d'augmenter la sécurité de l'utilisateur. Il s'agit d'une application empaquetée (toutes les ressources sont contenues dans un seul fichier zip) qui a les caractéristiques suivantes :
  • Approuvée par une boutique d'applications après une vérification du code.
  • Possède un manifeste d'application signé par la boutique d'applications
  • Utilise une politique de sécurité pour les contenus (Content Security Policy).
  • Implémente d'autres choses reliées à la sécurité. Pour plus d'informations, voir Sécurité.
• certified - Une Open Web App qui a été conçue afin d'assurer une fonctionnalité critique du système comme un téléphone ou une application des paramètres systèmes sur un smartphone. Ce type n'est pas prévu pour les applications tierces dans une boutique d'applications. Une application certifiée est une application empaquetée, similaire à une application privilégiée, sauf que toutes les permissions de l'appareil sont implicites. Elle doit être approuvée par le fabricant ou l'opérateur téléphonique de l'appareil qui l'utilise.

Exemple:

"type": "privileged"

version

(facultatif) Une chaîne de caractères représentant la version du manifeste. L’exécutable web n'utilise pas du tout cette valeur, elle est donc libre. Vous pouvez ajouter cette propriété dans le manifeste et récupérer sa valeur pour vous aider à gérer différents cas de mise à jour. Voir Mettre à jour les manifestes.

Gestion des chemins

Tout champ dans le manifeste qui contient des chemins, doit avoir des chemins absolus (par exemple, /images/mon-icone.png), et les chemins doivent être servis depuis la même origine que l'application.

De plus, il y a deux façons de définir launch_path :

• Si votre application est stockée à la racine d'un serveur web, par exemple mywebapp.github.com/, alors launch_path doit être défini à /.
• Si votre application est stockée dans un sous-repertoire, par exemple mymarket.github.com/mywebapp/, alors launch_path doit être défini à /mywebapp/.

Valider un manifeste

Pour valider un manifeste, utilisez ce site web :

https://marketplace.firefox.com/developers/validator

Vous pouvez aussi utiliser une API pour valider votre manifeste :

https://zamboni.readthedocs.org/en/latest/topics/api.html#validate

Servir les manifestes

Le manifeste de l'application doit être servi depuis la même origine que l'application.

Quand servi comme un fichier statique, il est recommandé que le manifeste soit stocké avec une extension de fichier .webapp. Les manifestes d'applications doivent être servis avec une entête Content-Type : application/x-web-app-manifest+json (Note : Ce n'est pas actuellement forcé par Firefox mais l'est par le Marketplace). Les manifestes peuvent être servis par SSL pour limiter certains types d’attaques.

Le document doit être en UTF-8 pour que l'application soit soumis au Firefox Marketplace. Il est recommandé d’omettre le byte order mark (BOM). D'autres encodages de caractères peuvent être renseignés avec un paramètre charset sur l'entête Content-Type (par exemple Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4), mais ne sera pas pris en compte par le Marketplace.

Les agents utilisateurs doivent, lorsque c'est possible, offrir un message compréhensible à l'utilisateur sur l'identité du site et le statut TLS, lors de l'installation d'une application.

Servir depuis Apache

Dans votre fichier .htaccess, vous devez ajouter la ligne suivante :

AddType application/x-web-app-manifest+json .webapp

Si vous n'avez pas de fichier .htaccess, créez-le dans le répertoire racine de votre serveur. Si cela ne marche pas, votre hébergeur peut attendre que vous ajoutiez aussi la ligne :

AddHandler x-web-app-manifest+json .webapp.

Servir depuis NGINX

Vous devez éditer votre fichier mime.types dans le répertoire conf. Il sera probablement situé soit dans /etc/nginx/ ou /opt/nginx/.

Vous devriez avoir quelque chose de similaire à ce qu'il y a ci-dessous. Ajoutez la dernière ligne.

types {
  text/html   html htm shtml;
  text/css    css;
  text/xml    xml;
  application/x-web-app-manifest+json   webapp;
}

Servir depuis GitHub

Si vous servez votre manifeste depuis GitHub Pages, GitHub le servira avec l'entête Content-Type : application/x-web-app-manifest+json. Vous devez utiliser l'extension de fichier .webapp pour votre manifeste. Exemple :

manifest.webapp.

Servir depuis Python

Si vous avez installé Python, vous pouvez facilement faire tourner un serveur depuis un répertoire local, en lançant Python et en collant ce bout de code :

import SimpleHTTPServer
import SocketServer
SimpleHTTPServer.SimpleHTTPRequestHandler.extensions_map['.webapp'] = 'application/x-web-app-manifest+json'
httpd = SocketServer.TCPServer(("", 3000), SimpleHTTPServer.SimpleHTTPRequestHandler)
httpd.serve_forever()

Mettre à jour des manifestes

Une application respecte les règles normales de cache du Web, et peut, si voulu, utiliser des mécanismes avancés pour améliorer le lancement comme HTML5 AppCache. En dehors de ceci, il n'y a pas de précautions particulières à prendre en compte pour mettre à jour les ressources normales d'une application.

Les Open Web Apps sont cependant différentes, dans la gestion du manifeste. Certains changements du manifeste peuvent nécessiter l'accord de l'utilisateur. En fonction de l'implémentation de l'exécutable Web, il peut être incertain si une mise à jour a eu lieue.

Pour résoudre ce problème, vous pouvez ajouter un champ version au manifeste de votre application. Vous pouvez vérifier plus tard la version en analysant la valeur retournée par la fonction navigator.mozApps.getInstalled(). Si la version que l'utilisateur a installée n'est pas à jour, vous pouvez déclencher une mise à jour en utilisant navigator.mozApps.install().

La valeur de version n'est pas utilisée par l'exécutable Web. Vous pouvez utiliser le format de version que vous souhaitez.

Notez aussi que des changements dans le manifeste qui introduisent des erreurs ou autres problèmes seront détectés si le manifeste a été soumis sur le Firefox Marketplace. Les erreurs sérieuses retireront l'application des listes d'applications. Des erreurs moins sérieuses déclencheront automatiquement une alerte pour une nouvelle vérification du code.