App manifest

Un Open Web App manifest contiene información que un navegador Web necesita para interactuar con una aplicación. Un manifest es una de las cosas claves que distinguen una Web App de un sitio web. Es un archivo  JSON con un nombre y una descripción para la aplicación, y también puede contener el origen de la aplicación, íconos, y los permisos requeridos por la aplicación, entre otras cosas. El navegador que maneja el manifest debe incorporar un Web runtime.

Para auto-publicar una aplicación desde una página web que permite controlar, se lanza la instalación de la aplicación (por ejemplo, llamando navigator.mozApps.install() desde un botón). Cuando una tienda o marketplace publica una aplicación, se dispara la instalación de la aplicación, proporcionándole al navegador la url del manifest de la aplicación alojada.

Véase About app manifests para un FAQ. También puedes encontrar nuestro útil manifest validator; En esta herramienta se verá tu manifest y te ayudará a erradicar cualquier error.

Creando un manifest de la aplicación

Esta sección detalla lo que necesitas crear y usar el manifiesto de la aplicación.

Convenciones: nombre archivo, ubicación, y formato

• Nombre: manifest.webapp (debe ser extension *.webapp)
• Ubicación: directorio raiz de tu aplicación
• Formato: JSON (Tiene que ser un formato válido)

Ejemplo de Manifest

El siguiente es un manifest mínimo. Tú puedes copiarlo en un archivo de texto y reemplazar los valores con tu información.

{
  "name": "My App",
  "description": "My elevator pitch goes here",
  "launch_path": "/",
  "icons": {
    "128": "/img/icon-128.png"
  },
  "developer": {
    "name": "Your name or organization",
    "url": "https://your-homepage-here.org"
  },
  "default_locale": "en"
}

Campos del Manifest

Los siguientes campos están permitidos en el manifest. Sólo hay dos campos obligatorios: name y description. Existen otros campos que son requeridos si usas ciertos campos. Esto se indíca en la documentación.

Los campos en el manifest pueden estar en cualquier orden. Campos en el manifest distintos de los indicados a continuación, serán ignorados.

activities

(Firefox OS, opcional) Especifíca una serie de Web Activities que esta aplicación soporta. Cada propiedad en este campo es una actividad. Nombres de actividades son texto libre de formato, y cada actividad está representada por un objeto. He aquí unas actividades de ejemplo del campo con una actividad denominada share:

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

El objeto de la actividad share en el ejemplo tiene tres propiedades: filters, href, y disposition. Estas son descritas a continuación.

• href - (requerido) Cuando otra aplicación o página web inicia una actividad que es compatible con esta aplicación, si esta aplicación es escogida para realizar la actividad, ésta especifíca la página que se abre. Se abrirá en la forma especificada por la propiedad disposition .
• disposition - (opcional) Especifíca cómo se presenta la página especificada en href cuando una actividad es invocada. El valor, si se especifíca, debe ser uno de los siguientes (si se omite, por defecto será window):
  • window - La página que maneja la actividad es abierta en un nueva "ventana"( en un dispositivo móvil ésta vista sustituirá a la aplicación original que pidió a la actividad). La página debe llamar a  navigator.setMessageHandler para cada actividad que ésta soporta y posteriormente ejecutar la actividad para la cual se recibe un mensaje. Además, si la actividad requiere regresar un valor, la página debe llamar a activity.postResult o activity.postError (Donde activity es el primer argumento suministrado a la función especificada por setMessageHandler) según sea apropiado. Estas especificaciones están especificadas con más detalle en Web Activities.
  • inline - La página que maneja la actividad se abrirá en una superposición (en un disositivo móvil esto será mostrado en una ventana emergente sobre la aplicación original que solicitó la actividad). Comportamiento subsiguiente es exactamente el mismo como si disposition fuese window.
• filters - (opcional) Un diccionario, cada propiedad de las cuales especifica un filtro. Estos filtrtos se aplicarán mientras se determina las aplicaciones adecuadas para el manejo de una actividad determinada. Los nombres de los filtros son de libre formato, pero sus valores deben ser una cadena o una matriz de cadenas (el tipo exacto depende del filtro ).

appcache_path

(opcional) La ruta absoluta a el cache de la aplicación en el manifest (AppCache). Cuando una Open Web App esta instalada , el AppCache manifest será recogida y analizada, y sus activos estáticas bajo el encabezado CACHE se almacenarán en cache.

"appcache_path": "/cache.manifest"

csp

(opcional) Especifica un Content Security Policy para la aplicación. Esta política se aplica a todas las páginas cargadas en la aplicación. Véase la Apps CSP page for more information.

default_locale

(requerida cuando locales esta presente). Una etiqueta de idioma (RFC 4646) que indica que idioma usa tu manifest. No incluya la etiqueta de idioma usada aquí en el campo locales. Esta es una buena práctica para definir default_locale incluso si usted no usa locales. El Firefox OS Marketplace usará esto para conocer en qué idioma está su manifest, para que pueda usar los valores de configuración regional correcta en los campos traducidos. Si no defines default_locale, el Marketplace tiene que adivinar el lenguaje basado en el serving locale. default_locale no es usado por el dispositivo que instala la aplicación.

Ejemplo para Inglés:

"default_locale": "en"​

description

(requerida) Una descripción legible para los usuarios de la aplicación (la longitud maxima es 1024 caracteres).

developer

(opcional) Información acerca del desarrollador de la aplicación. Tienes estas propiedades:

• name - El nombre del desarrollador.
• url - La dirección URL de un sitio que contiene más información sobre el desarrollador de la aplicación. Esta URL tipicamente es mostrada cuando los usuarios hacen click sobre el nombre del desarrollador de la aplicación mientas visualizan detalles acerca de esta dentro del panel de control (o navegador).

fullscreen

(Sólo Firefox OS , opcional) Establezca esta propiedad a true o false para indicar si se debera lanzar la aplicación en modo de pantalla completa. Ejemplo:

"fullscreen": "true"

íconos

(opcional) Un mapa del tamaño de los íconos de los URIs de los íconos (que pueden ser  absolute paths o data URIs). Las Rutas comenzando con / son tratadas como relativas a el origen de la aplicación. Los íconos deben ser cuadrados y están destinados a representar visualmente la aplicación. Los íconos no deberian tener fondos solidos qué se extienden a todas las esquinas del ícono.

Para Windows 7 y Android, los siguientes tamaños de íconos estan soportados:

• 16 x 16
• 32 x 32
• 48 x 48
• 64 x 64
• 128 x 128
• 256 x 256

Para Firefox OS, puedes seguir los app icon guidelines para Firefox OS. Los íconos deben ser proporcionados sin una gota de sombra y una close cropped canvas en los siguientes tamaños:

• 30 x 30
• 60 x 60

Tu puedes especificar múltiples íconos como este ejemplo:

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

installs_allowed_from

(opcional) Un arreglo de origenes (scheme+dominio, por ejemplo https://marketplace.example.com) qué están permitidos para lanzar al instalación de esta aplicación. Este campo te permite habilitar explicitamente sólo ciertos sitios o tiendas, con quien tiene una relación para instalar la aplicación. El arreglo ["*"] significa qué las instalaciones de esta aplicación estan permitidas desde cualquier sitio. Este es el valor predeterminado. Nota qué [] sería no permitir la instalación desde cualquier sitio, incluyendo nuestro propio sitio. Aquí está un ejemplo permitiendo instalaciones desde cualquier sitio:

"installs_allowed_from": ["*"]

launch_path

(opcional, requerida para aplicaciones empaquetadas) La ruta de origen que se carga cuando la aplicación inicia. Si no se proporciona, el origen de la app se trata como el dominio de la URL. Ver Path Handling.

En una app empaquetada, este campo especifíca el punto de partida del contenido local al archivo zip que contiene la app empaquetada. Por ejemplo, si launch_path tiene un valor de /myApp/index.html, cuando la app empaquetada es cargada se abrirá el archivo /myApp/index.html.

locales

(opcional) Un mapa de uno a más locale-specific anulaciones de los datos contenidos en el manifest, las cuales las IUs usan para proveer vistas localizadas basadas en los accesos locales. Por ejemplo, si tienes hablantes italianos instalando tu app, probablemente querrás que vean una interfaz de usuario localizada a su idioma. Cada entrada local está marcada con una etiqueta (RFC 4646) y contienen una representación dispersa del manifest. Cualquier archivo presente en el campo locale sobre-escribe los campos que concuerdan en el manifest. No puedes sobre-escribir estos campos: default_locale, locales a sí mismos, y installs_allowed_from. Un manifest que sobre-escribe cualquiera de estos campos es invalido. Cuando locales está presente, default_locale también debe de estarlo.

Ejemplo con Español e Italiando:

"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/"
  }
}
}

nombre

(requerido) Un nombre legible para la aplicación (la longitud máxima es de 128 caracteres).

orientación

(solo Android y Firefox OS, opcional) Un array que define las orientaciones a las cuales las aplicaciones estarán bloqueados incluso si la orientación del dispositivo cambia. Cada entrada en el array puede ser uno de los portrait, landscape, portrait-primary, landscape-primary, portrait-secondary or landscape-secondary. Las opciones con bloqueo primario y secundario bloquearán la orientación del dispositivo en solo una orientación, incluso si la orientación del dispositivo cambia. Las opciones sin primario y secundario combinan ambas reglas de primario y secundario juntos. Las opciones adicionalmente con el sufijo -secondary implementan una rotación de 180 grados para las opciones que no tienen el sufijo. Por ejemplo, sostener el teléfono boca abajo (pero de una manera en que el ancho es menor que la altura), implica la orientación portrait-secondary. Si este campo tiene un valor válido, el tiempo de ejecución no va a cambiar la orientación de la vista renderizando la aplicación incluso si el dispositivo es volteado. Ejemplo:

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

permisos

(opcional) La serie de permisos que la app necesita. Una app debe listar cada API que intenta utilizar que requiera el permiso del usuario. Si una app trata de utilizar una de estas APIs sin la entrada correspondiente en este campo, fallará.

El campo de permisos es un objeto, con cada propiedad especificando un solo permiso. Cada entrada a la API debe tener una descripción apropiada. Algunas APIs tambien requieren acceso apropiado. Ejemplo del campo permissions:

"permissions": {
"contacts": {
  "description": "Required for autocompletion in the share screen",
  "access": "readcreate"
  },
"alarms": {
  "description": "Required to schedule notifications"
  }
}

• description - Una cadena que especifica la intención de solicitar utilizar esta API. Esta propiedad es obligatoria.
• access -Una cadena especificando el tipo de acceso requerido para el permiso. Esta propiedad solo es requerida para unas cuantas APIs. Los posibles valores son read, readwrite, readcreate y createonly.

Los permisos de las APIs están listados a continuación. Si un API necesita una propiedad access, esta es mencionada. Para más información sobre cuando estos permisos son soportados, ve a App permissions.

• alarms - Programar una notificación, o programa una aplicación para que ésta comience.
• browser - Permite el uso de un navegador.
• contacts - Agregar, leer, o modificar contactos de la agenda en el dispositivo y leer contactos desde la tarjeta SIM;. access propiedad requerida: una de readonly, readwrite, readcreate o createonly.
• device-storage:music/device-storage:videos/device-storage:pictures/device-storage:sdcard - Agregar, leer o modificar archivos almacenados en el punto central del dispositivo. access propiedad requerida: una de readonly, readwrite, readcreate o createonly.
• fmradio - Controla el radio FM.
• geolocation - Obtiene la actual localización del usuario.
• storage - Utiliza localStorage y IndexedDB sin limitaciones de tamaño.
• systemXHR - Hacer las peticiones HTTP sin orígenes de restricción.
• tcp-socket - Crear y comunicarse a través de puertos TCP.
• wifi-manage - Enumerar las redes WiFi disponibles, obtener el alcance de la red, conectar a una red.

Además, algunas propiedades que solo están disponibles para apps certificadas:

• backgroundservice - Habilita una aplicación web para correr en segundo plano y llevar a cabo tareas como la sincronización o responder a los mensajes entrantes.
• bluetooth - Acceso de bajo nivel para las características del Bluetooth.
• camera - Tomar fotos, hacer video y controlar la cámara. La razón por la cual ésta característica está limitada a apps certificadas fue por el sandbox que corren las aplicaciones en accesos preventivos al hardware de la cámara. Nuestra meta es hacerla disponible para aplicaciónes 3rd party lo más pronto posible, pero no tendremos tiempo para hacerlo posible en la primera entrega.
• desktop-notification - Despliega una notificación en el escritorio del usuario.
• mobileconnection - Obtener información acerca de la comunicación móvil de voz y datos de conexión.
• power - Apaga o enciende la pantalla, control del CPU, corriente del dispotivo, y cosas por el estilo. Escuchar e inspeccionar los sucesos de bloqueo de recursos.
• settings - Configurar o ver los ajustes del dispositivo. access propiedad requerida: una de readonly o readwrite.
• sms - Enviar y revibir SMS.
• telephony - Acceso a toda la telefonía- APIs relacionadas.
• time - (antes systemclock) Fija el horario. (La información del tiempo de zona está controlado por la configuración de la API.)
• webapps-manage - Obtiene acceso al API navigator.mozApps.mgmt para administrar las Open Web Apps.

type

(opcional) El tipo de aplicación, que puede ser web, privileged, o certified. Los tipos son descritos a continuación.

• web - Una app regular. Los permisos son limitados a esta lista en el manifest en el campo de permissions. Si no especificas el campo type en el manifest, web es el tipo predeterminado.
• privileged - Una Open Web App autenticada que ha sido aprobada por una tienda de aplicaciones como el Firefox OS Marketplace. Algunas APIs de seguridad o privacidad solo están disponibles para apps tipo  privileged. Su propósito es dar más seguridad a un usuario para aplicaciones que desean tener acceso a dicha API. Hay un packaged app (todos los recursos en un archivo zip) que tiene las siguientes características adicionales:
  • Aprovadas por una tienda de aplicaciones después de una revisión de código o el equivalente.
  • Tiene un app manifest firmado por la tienda de aplicaciones.
  • Usa Content Security Policy.
  • Implementa otras cosas relacionadas a la seguridad. Para más información ve a: Security.
• certified - Una Open Web App que está destinada para una función crítica de sistema como el marcado predetrminado o el sistema de configuración de apps en un smartphone. No está destinado a aplicaciones 3rd party en una tienda de aplicaciones. Una app certificada es una app empaquetada que es similar a una app privileged, excepto que todos los permisos de los dispositivos son implicitos. Debe ser aprobado por el OEM o soporte para el dispositivo que la utiliza.

Ejemplo:

"type": "privileged"

version

(opcional) Una cadena que representa la versión del manifest. Este valor no es usado en el tipo Web en ningún momento, por lo tanto este puede ser cualquier valor. Puedes insertar esta cadena dentro del manifest y extraerla para ayudar a sobrellevar algunos casos de actualización. Ver Updating manifests.

Ejemplo:

"version": "1.0.1"

Manejo de rutas

Todos los campos que mantienen una ruta en el manifest deben de ser rutas absolutas (por ejemplo, /images/myicon.png), y las rutas deben ser atendidas desde el mismo origen que la app.

También, hay dos maneras de establecer launch_path:

• Si tu app está almacenada en la raíz de un servidor Web, por ejemplo mywebapp.github.com/, entonces launch_path debe ser fijado a /.
• De otra manera, si tu app está almacenada en un subdirectorio, por ejemplo mymarket.github.com/mywebapp/, entonces launch_path debe ser fijado a /mywebapp/.

Validando un manifest

Para validar un manifest, usa este sitio: https://marketplace.firefox.com/developers/validator

Incluso hay una API que puedes usar para validar el manifest: https://zamboni.readthedocs.org/en/latest/topics/api.html#validate

Sirviendo manifests

El manifest de la app debe ser servido desde el mismo origen que la app.

Cuando es servido desde archivos estáticos, se recomienda que el manifest esté almacenado con una extensión de archivo de .webapp. Los manifests deben ser servidos con una cabecera de Content-Type de application/x-web-app-manifest+json. Esta es actualmente no forzada por Firefox pero lo es por el Marketplace. Firefox OS solamente revisa este si el origen de la página donde el usuario ejecuta la instalación es diferente que el origen de la misma webapp.

Los manifets pueden ser servidos sobre SSL para mitigar cierta clase de ataques.

El documento debe ser UTF-8 para que así la app pueda ser enviada al Firefox OS Marketplace. Es recomendado omitir la marca de orden de byte (BOM, por sus siglas en inglés). Otras codificaciones pueden ser especificadas con un parámetro charset en la cabecera Content-Type (por ejemplo Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4), aunque esto no viene a respetarse por el Marketplace.

Agentes usuario siempre que sea posible deben manejarse mensajes a la identidad de sitio y el estado de TLS cuando se pida confirmación al usuario para instalar una aplicación.

Servicio desde Apache

Si es archivo .htaccess, debes agregar lo siguiente:

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

Si no tienes un archivo .htaccess, crealo en el directorio raíz de tu servidor. Si esto no funciona, tu host puede requerir que agregues AddHandler x-web-app-manifest+json .webapp.

Servicio desde NGINX

Necesitas editar tu archivo mime.types en el directorio conf. Este probablemente se encuentra en /etc/nginx/ o /opt/nginx/.

Debes tener algo similar a lo siguiente. Agrega la última línea.

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

Servicio desde GitHub

si tienes servido tu archivo manifet desde GitHub Pages, GitHub lo servirá con la cabecera Content-Type de application/x-web-app-manifest+json. Deberás usar la extensión de archivo .webapp en tu archivo manifest. Ejemplo: manifest.webapp.

Servicio desde Python

Si tienes instalado python, fácilmente puedes correr un servidor desde el directorio local, corriendo python y pegando el mismo:

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

Actualizando manifests

Para más información sobre actualizar aplicaciones, ver Updating apps.