Что такое manifest json

Пишем правильный манифест для сайта

Думаю, многие знают о возможности добавления иконки сайта на рабочий стол мобильного устройства. Это удобно и причины могут быть разные (нету мобильного приложения, предоставляющего туже информацию, либо вы хотите сразу открыть определенную страницу сайта и т.д.). За некоторые свойства того, как будет отображаться сайт и как будет выглядеть иконка после добавления и отвечает файл манифеста.

Манифест для сайта – это простой JSON-файл, который позволяет вам настроить следующие вещи:
1. Какая будет иконка у пользователя, после того как он добавит ваш сайт на рабочий стол
2. Как будет запускаться ваш сайт (с адресной строкой, без нее или в полноэкранном режиме)
3. Splash screen
4. Цветовую тему
5. Ориентацию экрана
6. Начальный url
и многое другое

Подробнее

Чтобы показать, как manifest влияет на отображение сайта, я создал простое, тестовое веб-приложение, которые возвращает название региона по коду.

Сначала зафиксируем положение дел до добавления файла манифеста.

После того как пользователь добавил иконку, она будет выглядеть так (на Андроид 5.0)
Название браузер выдернул из тега tilte. Так что, если у вас нету файла манифеста, то хотя бы title должен быть нормальным. А вот иконка в виде буквы “G” появилась сама (не понятно, почему именно G).
А сам сайт будет выглядеть так

Тут, собственно, ничего особенного, кроме того, что мы можем убрать адресную строку, чтобы приложение было похоже на нативное.

Встречайте, manifest.json!

Генерируй и властвуй.

Конечно, можно написать весь манифест ручками, но это скучно, долго и можно ошибиться. Уже нашлось немало умельцев, которые автоматизировали этот процесс. Ниже небольшой обзор инструментов для автоматической генерации манифеста.

brucelawson.github.io/manifest — все что вам нужно – заполнить поля (есть краткое описание каждого параметра, так что процесс довольно легкий), остальное за вас сделает генератор.

www.favicon-generator.org — хоть прямое назначение этого сайта генерировать иконки, а не манифест. Он все же его создает и в отличии от предыдущего у вас уже будут и иконки (для iOS и Аднроид) и манифест. Правда, манифест придется подправить (изменить имя и прочее настройки).

manifest-validator.appspot.com — этот инструмент предназначен для валидации вашего манифеста.

Результат

Итак иконки нарисовали, манифест сделали. Дальше надо сообщить браузеру о манифесте, добавив в тег head следующие

Все. Смотрим, что получилось
Иконка:

Слева до. Справа после (иконка получилась невпечатлительная, с удовольствием поменяю, если пришлете лучше). Тут уже заметно, что Android использовал имя из поля short_name, так как name не помещается, видимо.

Загрузка приложения:

Тут самые приятные изменения. Во-первых, вместо белого экрана вы видите подобие splash screen, который сам создается системой из иконки, полного имени и цвета, указанного в манифесте (возможно, это происходит только на android 5.0 выше). Во-вторых, этот splash screen плавно исчезает, что визуально красиво.

Сам сайт:

Тут тоже все стало лаконично. Без UI браузера сайт смотрится гораздо лучше и больше похож на нативное приложение.

Я перечислил не все свойства, которые можно указать в файле манифеста. С полным списком можно ознакомиться здесь
Демо приложение
Репозиторий приложения

Также необходимо подчеркнуть, что все это не будет работать на яблочных устройствах. На них можно достичь приблизительно такого результата, только надо использовать другой способ.

Источник

Манифест приложения

Манифест приложения описывает ресурсы, также называемые возможностями приложения, которые требуется приложению. У каждого приложения имеется манифест приложения.

Приложения должны согласиться использовать возможности, указав необходимые ресурсы в разделе Capabilities (возможности) манифеста приложения. Никакие возможности не включены по умолчанию. Если приложение запрашивает возможность, которая отсутствует в списке, запрос отклоняется. Если файл манифеста приложения содержит ошибки, попытки загрузки неопубликованного приложения завершаются сбоем. Манифест каждого приложения должен быть сохранен как файл app_manifest.json в корневом каталоге папки приложения на компьютере.

Шаблоны Azure Sphere автоматически создают манифест приложения по умолчанию при создании приложения. Необходимо изменить манифест по умолчанию, чтобы указать список возможностей, которые требуются вашему приложению. Каждый пример Azure Sphere также содержит манифест приложения. Если приложение основано на примере, вам, вероятно, потребуется изменить манифест.

Различные устройства Azure Sphere могут предоставлять функции микросхемы различными способами. Таким образом, значение, используемое в манифесте для обнаружения определенной функции, например вывод GPIO, может различаться в зависимости от оборудования, для которого выполняется разработка. Управление зависимостями целевого оборудования предоставляет дополнительные сведения о целевых объектах оборудования для высокоуровневого приложения. в манифесте приложения для высокоуровневого приложенияиспользуйте константы, определенные в JSON-файле, в папке хардваредефинитионс каталога установки пакета SDK Microsoft Azure Sphere. точное расположение каталога установки будет отличаться в Windows и Linux. В приложении, поддерживающем режим реального времени (RTApp), используйте необработанные значения, перечисленные в разделе Содержимое манифеста приложения.

Когда приложение загружается без публикации или разворачивается на устройстве, среда выполнения Azure Sphere считывает манифест приложения, чтобы выяснить, какие возможности приложению разрешено использовать. Попытки получить доступ к ресурсам, которые не перечислены в манифесте, приведут к ошибкам API, например EPERM (отказ в доступе). Только одно приложение на устройстве может использовать ресурс. Если установить приложение, которое запрашивает уже используемый ресурс, попытка завершится сбоем.

Содержимое манифеста приложения

Манифест приложения содержит следующие элементы.

Раздел Capabilities поддерживает следующие элементы.

Высокоуровневые приложения могут использовать значения возможностей из файлов определения оборудования или необработанные значения. Но вы не можете одновременно использовать оба типа значений в одной и той же возможности. Ртаппс может использовать только необработанные значения для возможностей.

Раздел MutableStorage поддерживает следующие элементы.

Источник

Что такое manifest json

This specification defines a JSON-based file format that provides developers with a centralized place to put metadata associated with a web application. This metadata includes, but is not limited to, the web application’s name, links to icons, as well as the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default screen orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to «scope» a web application to a URL. This restricts the URLs to which the manifest is applied and provides a means to «deep link» into a web application from other applications.

Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.

Implementors need to be aware that this specification is not stable. However, aspects of this specification are shipping in at least one browser (see links to implementation status at the top of this document). Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.

Web Application Manifest

A is a [[JSON]] document that contains startup parameters and application defaults for when a web application is launched.

A [=manifest=] can have any of the following members at its root, all of which are optional. The members can appear in any order.

Although it is optional for any member to appear in a manifest, some user agents might require one or more to be present to take full advantage of the capabilities afforded by this specification.

Examples

This section shows how developers can make use of the various features of this specification.

Typical structure

The following shows a typical manifest.

Using a `link` element to link to a manifest

The example also shows how to use the link type «manifest» and how to use other [^meta^] and [^link^] elements to give the web application a fallback name and set of icons.

The IANA registered file extension for the manifest is `.webmanifest`. Some web servers recognize this extension and transfer the file using the standardized application manifest media type ([=application\/manifest+json=]). Developers can also choose a different extension (e.g. `.json`) or none at all (e.g. `/api/GetManifest`), but are encouraged to transfer the manifest using the [=application\/manifest+json=] [=MIME type=], although any [=JSON MIME type=] is ok.

Declaring multiple icons

In the following example, the developer has made the following choices about the icons associated with the web application:

Creating shortcuts

In the following example, the developer has included two shortcuts. Assuming the manifest’s URL is https://example.com/manifest.webmanifest :

Understanding «scope»

For example, `<"scope": "/">` means that the manifest applies to every document in an origin. On the other hand, `<"scope": "/racer/">` means that only documents within the path «/racer/» are [=URL/within scope=]: so «/racer/race1.html», «/racer/race2.html», etc. would all be [=URL/within scope=], but «/elsewhere/» and anything at the root «/» would be «out of scope» and the manifest wouldn’t apply to documents in those paths. Only one scope path is supported. See [[[#nav-scope]]] for the technical details.

[=Applying=] a manifest means that any members that affect presentation found in the manifest will come into effect, such as display «fullscreen», or applying a particular screen orientation. As long as the application is navigated to URLs that are [=URL/within scope=], the browser will continue to apply the manifest. However, navigating the web applications «out of scope» will cause the manifest to no longer be applied, and the browser will apply its own defaults. This will cause, for example, the application to no longer be displayed in fullscreen, and instead be displayed as a regular web page in a browser tab. It’s left up to implementers to decide how to deal with web pages being navigated in and out of scope. See [[[#applying]]] for the technical details.

Finally, as it’s possible that a user can install a web application from any document within an origin, it’s good practice to always declare a [=manifest/scope=] member in a manifest. If the [=manifest/scope=] member is missing from the manifest, then the path of the [=manifest/start_url=] member is used as a fallback. And if the [=manifest/start_url=] member is also missing, then the document URL from which the web application is installed gets used as the scope. To be sure you don’t get any unexpected navigation behavior, always include a [=manifest/scope=] member preferably set to `»/»`.

`dir` member

The [=manifest’s=] member specifies the for the localizable members of the manifest. The [=manifest/dir=] member’s value can be set to a text-direction.

The are the following, implying that the value of the localizable members is by default:

«» Left-to-right text. «» Right-to-left text. «» (default) No explicit directionality.

The is the [=list=] « «[=text-direction/ltr=]», «[=text-direction/rtl=]», «[=text-direction/auto=]» ».

When displaying the localizable members to an end-user, the use agent SHOULD:

`lang` member

The [=manifest’s=] member is a string in the form of a language tag that specifies the primary language for the values of the manifest’s localizable members (as knowing the language can also help with directionality).

A is a string that matches the production of a `Language-Tag` defined in the [[BCP47]] specifications (see the IANA Language Subtag Registry for an authoritative list of possible values). That is, a language range is composed of one or more that are delimited by a U+002D HYPHEN-MINUS («-«). For example, the ‘`en-AU`’ language range represents English as spoken in Australia, and ‘`fr-CA`’ represents French as spoken in Canada. Language tags that meet the validity criteria of [[RFC5646]] section 2.2.9 that can be verified without reference to the IANA Language Subtag Registry are considered structurally valid.

`name` member

The [=manifest’s=] member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon).

The [=manifest/name=] member serves as the accessible name of an [=installed web application=].

When [=processing a manifest=], the [=process a text member=] algorithm is used to process the [=manifest/name=] member.

`short_name` member

The [=manifest’s=] member is a string that represents a short version of the name of the web application. It is intended to be used where there is insufficient space to display the full name of the web application.

When [=processing a manifest=], the [=process a text member=] algorithm is used to process the [=manifest/short_name=] member.

`scope` member

The [=manifest’s=] member is a string that represents the [=manifest/navigation scope=] of this web application’s application context.

The «default scope» (when [=manifest/scope=] member is missing, empty, or failure) is the start URL, but with its filename, query, and fragment removed.

`icons` member

The [=manifest’s=] member are images that serve as iconic representations of the web application in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS ‘s task switcher and/or system preferences.

If there are multiple equally appropriate images in [=manifest/icons=], a user agent MUST use the last one declared in order at the time that the user agent collected the list of [=manifest/icons=]. If the user agent tries to use an icon but that icon is determined, upon closer examination, to be inappropriate (e.g. because its content type is unsupported), then the user agent MUST try the next-most-appropriate icon as determined by examining the [=manifest image resource=]’s members.

When [=processing a manifest=], the [=process image resources=] algorithm is used to process the [=manifest/icons=] member.

`display` member

The [=manifest’s=] member represents the developer’s preferred display mode for the web application. Its value is a [=display mode=].

`orientation` member

The [=manifest’s=] member is a string that serves as the default screen orientation for all top-level browsing contexts of the web application. The possible values are those of the <> enum, which in this specification are referred to as the (i.e., «any», «natural», «landscape», «portrait», «portrait-primary», «portrait-secondary», «landscape-primary», or «landscape-secondary»).

If the user agent supports the value of the [=manifest/orientation=] member as the default screen orientation, then that serves as the default screen orientation for the life of the web application (unless overridden by some other means at runtime). This means that the user agent MUST return the orientation to the default screen orientation any time the orientation is unlocked [[SCREEN-ORIENTATION]] or the top-level browsing context is navigated.

Although the specification relies on the [[SCREEN-ORIENTATION]]’s <>, it is OPTIONAL for a user agent to implement the [[SCREEN-ORIENTATION]] API. Supporting the [[SCREEN-ORIENTATION]] API is, of course, encouraged.

Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [[SCREEN-ORIENTATION]] API).

`start_url` member

The [=manifest/start_url=] member is purely advisory, and a user agent MAY ignore it or provide the end-user the choice not to make use of it. A user agent MAY also allow the end-user to modify the URL when, for instance, a bookmark for the web application is being created or any time thereafter.

Privacy consideration: [=manifest/start_url=] tracking

It’s conceivable that the [=manifest/start_url=] could be crafted to indicate that the application was launched from outside the browser (e.g., `»start_url»: «index.html?launcher=homescreen»`). This can be useful for analytics and possibly other customizations. However, it is also conceivable that developers could encode strings into the start_url that uniquely identify the user (e.g., a server assigned UUID ). This is fingerprinting/privacy sensitive information that the user might not be aware of.

Given the above, it is RECOMMENDED that, upon installation, or any time thereafter, a user agent allows the user to inspect and, if necessary, modify the start URL of an application.

`id` member

The [=manifest’s=] member is a string that represents the for the application. The [=identity=] takes the form of a URL, which is same origin as the start URL.

The [=identity=] is used by user agents to uniquely identify the application universally. When the user agent sees a manifest with an [=identity=] that does not correspond to an already-installed application, it SHOULD treat that manifest as a description of a distinct application, even if it is served from the same URL as that of another application. When the user agent sees a manifest where |manifest|[«id»] [=url/equal|equals=] the [=identity=] of an already-installed application, it SHOULD be used as a signal that this manifest is a replacement for the already-installed application’s manifest, and not a distinct application, even if it is served from a different URL than the one seen previously.

The [=identity=] can be used by a service that collects lists of web applications to uniquely identify applications.

The [=identity=] is processed like a URL but it doesn’t point to a resource that can be navigated to, so it’s not required to be [=URL/within scope=].

Below table shows some example `id`s resulting from the [=process the `id` member=] steps.

Since [=manifest/id=] is resolved against [=manifest/start_url=]’s [=URL/origin=], providing «../foo», «foo», «/foo», «./foo» all resolves to the same [=identifier=]. It is As such, best practice is to use a leading «/» to be explicit that the id is a root-relative url path. Also, standard encoding/decoding rules are apply to the id processing algorithm, as per the [[[URL]]].

`theme_color` member

The [=manifest’s=] member serves as the for an application context. What constitutes a is defined in [[HTML]].

If the user agent honors the value of the [=manifest/theme_color=] member as the default theme color, then that color serves as the theme color for all browsing contexts to which the manifest is applied. However, a document may override the default theme color through the inclusion of a valid [[HTML]] [^meta^] element whose [^meta/name^] attribute value is `»theme-color»`.

The user agent MAY ignore the theme color’s [=alpha component=] based on the context. For example, in most environments, the theme color cannot be transparent.

Implementors MAY override the value defined by the [=manifest/theme_color=] member to support prefers-color-scheme.

When [=processing a manifest=], the [=process a color member=] algorithm is used to process the [=manifest/theme_color=] member.

`related_applications` member

A is an application accessible to the underlying application platform that has a relationship with the web application.

The [=manifest’s=] member lists related applications and serves as an indication of such a relationship between web application and related applications. This relationship is unidirectional and unless a listed application claims the same relationship, the user agent MUST NOT assume a bi-directional endorsement.

Example of usages of the `related_applications` could be a crawler that would use that information to gather more information about the web application or a browser that could suggest a listed application as an alternative if the user wants to install the web application.

`prefer_related_applications` member

The [=manifest’s=] member is a [=boolean=] that is used as a hint for the user agent to say that related applications should be preferred over the web application. If the `prefer_related_applications` member is set to `true`, and the user agent wants to suggest to install the web application, the user agent might want to suggest installing one of the related applications instead.

`background_color` member

The [=manifest’s=] member describes the expected background color of the web application. It repeats what is already available in the application stylesheet but can be used by the user agent to draw the background color of a web application for which the manifest is known before the files are actually available, whether they are fetched from the network or retrieved from disk.

The [=manifest/background_color=] member is only meant to improve the user experience while a web application is loading and MUST NOT be used by the user agent as the background color when the web application’s stylesheet is available.

Implementors MAY override the value defined by the [=manifest/background_color=] member to support prefers-color-scheme.

When [=processing a manifest=], the [=process a color member=] algorithm is used to process [=manifest/background_color=] member.

`shortcuts` member

The [=manifest’s=] member is an [=list=] of shortcut items that provide access to key tasks within a web application.

Shortcuts could, for instance, be used to link directly to a user’s timeline within a social media application or to their recent orders in an e-commerce context.

Developers are encouraged to order their shortcuts by priority, with the most critical shortcuts appearing first in the list.

How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system.

A user agent SHOULD expose shortcuts via interactions that are consistent with exposure of an application icon’s context menu in the host operating system (e.g., right click, long press). A user agent SHOULD render the shortcuts in the same order as they are provided in the manifest. A user agent SHOULD represent the shortcuts in a manner consistent with exposure of an application icon’s context menu in the host operating system. A user agent MAY truncate the list of shortcuts presented in order to remain consistent with the conventions or limitations of the host operating system.

Manifest life-cycle

This section defines algorithms for [=processing a manifest=], and applying a manifest.

A user agent MUST support the link type «manifest» and the associated steps for how to fetch and process the linked resource.

Processing the manifest

The following algorithm provides an : other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm. They SHOULD NOT modify the existing values already in the manifest object.

The [=application manifest/processing extension-point=] is meant to help avoid issues related to monkey patching.

The steps for are given by the following algorithm. The algorithm takes [^link^] |el:HTMLLinkElement| and a [=Response=] |response|.

Processing color members

Only [=sRGB=] colors, and colors the user agent can convert to [=sRGB=] without any outside knowledge (e.g., `»AliceBlue»`), are supported. For example, `lab(…)` or `color(display-p3, …)` can be converted to [=sRGB=] without outside knowledge, but `color(—custom-profile, …)` would require finding a matching «@color-profile» rule which cannot be specified in the manifest.

Processing text members

Applying the manifest

A [=Document/processed manifest=] is to a top-level browsing context, meaning that the members of the [=Document/processed manifest=] are affecting the presentation or behavior of a browsing context.

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent MUST immediately navigate to the deep link with historyHandling set to «`replace`». Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with historyHandling set to «`replace`».

The start URL is not necessarily the value of the [=manifest/start_url=] member: the user or user agent could have changed it when the application was installed.

The appropriate time to apply a manifest is when the application context is created and before [=navigate|navigation=] to the start URL begins.

Updating the manifest

Manifest image resources

Each is an [=image resource=] that is conceptually part of a web application, suitable to use in various contexts depending on the semantics of the member that is using the object (e.g., an icon that is part of an application menu, etc.).

A [=manifest image resource=] differs from a [=image resource=] in that it can have an additional [=manifest image resource/purpose=] member.

User agents MAY modify the images associated with an [=manifest image resource=] to better match the platform’s visual style before displaying it to the user, for example by rounding the corners or painting it in a specific color. It is recommended that developers prepare their image resources for such scenarios to avoid losing important information through, e.g., change of color or clipped corners.

`purpose` member

For example, an icon with purpose «[=icon purpose/monochrome=]» could be used as a badge or pinned icon with a solid fill, visually distinct from an application’s full color launch icon. The user agent uses the value of the [=manifest image resource/purpose=] member as a hint to determine where and how an [=manifest image resource/purpose=] is displayed. Unless declared otherwise by the developer, a user agent can use an icon for [=icon purpose/any|any purpose=].

The are as follows:

A user agent can present this icon where a monochrome icon with a solid fill is needed. The color information in the icon is discarded and only the alpha data is used. The icon can then be used by the user agent like a mask over any solid fill. The image is designed with icon masks and safe zone in mind, such that any part of the image that is outside the safe zone can safely be ignored and masked away by the user agent. (default) The user agent is free to display the icon in any context.

The is the [=list=] « «[=icon purpose/monochrome=]», «[=icon purpose/maskable=]», «[=icon purpose/any=]» ».

If an icon contains multiple purposes, it could be used for any of those purposes. If none of the stated purposes are recognized, the icon is totally ignored. For example, if an icon has purpose `»monochrome fizzbuzz»`, then it could be used as a monochrome icon, as `»monochrome»` is a valid purpose. However, if an icon just has the purpose `»fizzbuzz»`, then it will be ignored.

Content security policy

The security policy that governs whether a user agent can fetch an icon image is governed by the `img-src` directive [[CSP3]] associated with the manifest’s owner <>.

For example, given the following `img-src` directive in the `Content-Security-Policy` HTTP header of the manifest’s owner <>:

And given the following `manifest.webmanifest`:

The fetching of icon resources from `icons.example.com/lowres` would succeed, while fetching from `other.com/hi-res` would fail.

Icon masks and safe zone

Some platforms have their own preferred icon shape, but as web applications should work across multiple platforms, it is possible to indicate that an icon can have a user-agent-specified mask applied by adding the [=icon purpose/maskable=] purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different masks and background colors in different places throughout the platform.

The is the area within a [=icon purpose/maskable=] icon which is guaranteed to always be visible, regardless of user agent preferences. It is defined as a circle with center point in the center of the icon and with a radius of 2/5 (40%) of the icon size, which means the smaller of the icon width and height, in case the icon is not square.

Designers of [=icon purpose/maskable=] icons will want to make sure that all important parts are within the safe zone.

The safe zone is a centrally positioned circle, with radius 2/5 (40%) of the minimum of the icon’s width and height.

All pixels in this zone are guaranteed to be seen in all masks. Pixels outside the safe zone are not guaranteed to (but can) be visible depending on the applied mask.

The user agent MAY apply a mask of any size, making any pixels that are more than 2/5ths of the image size (minimum of width and height if non-square) away from the center (the safe zone) transparent.

The user agent MUST NOT make any pixel within the safe zone transparent.

The user agent MAY enlarge the icon by adding additional padding.

If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid fill (e.g., white) of the user agent’s choice.

It is suggested that designers avoid using transparent pixels in maskable icons.

Examples of masks

By staying inside the safe zone, most icons will have around 10% padding on the top, bottom, right and left with no content or non-essential content, such as an icon background. It is suggested that developers check their icon when all but the safe zone is masked out.

Icons with «maskable» purpose

Mask examples

Monochrome icons and solid fills

Some platforms enforce that icons be displayed with a such as a single color, where only the transparency of the icon can be declared in a [=manifest=]. As web applications need to work across multiple platforms, it is possible to indicate that an icon can have an user-agent-specified color applied by adding the [=icon purpose/monochrome=] purpose. This allows the platform to ensure that the icon looks well integrated with the platform, and even apply different colors and padding in different places throughout the platform.

When presenting a [=icon purpose/monochrome=] icon, the user agent MUST NOT independently display the red component, green component, or blue component of a pixel. The user agent SHOULD display each pixel with its original alpha value, but with a red, green, and blue value of the user agent’s choosing. It is RECOMMENDED that the user agent use the same color value for all pixels.

Designers of [=icon purpose/monochrome=] icons could set all pixels to black and only use transparency to create a silhouette of their icon.

The user agent MAY enlarge the icon by adding additional padding.

The user agent MAY add a background of any color behind transparent pixels, and SHOULD ensure that the background has sufficient contrast with the icon.

Example usage of monochrome icons

Usage examples

Processing image resources

Shortcut items

Each is an [=ordered map=] that represents a link to a key task or page within a web app. It has the following members:

A user agent can use these members to assemble a context menu to be displayed by the operating system when a user engages with the web app’s icon. When the user invokes a shortcut from the operating system menu, the user agent SHOULD run launching a shortcut.

`name` member

The [=shortcut item’s=] member is a string that represents the name of the shortcut as it is usually displayed to the user in a context menu.

`short_name` member

The [=shortcut item’s=] member is a string that represents a short version of the name of the shortcut. It is intended to be used where there is insufficient space to display the full name of the shortcut.

`description` member

The [=shortcut item’s=] member is a string that allows the developer to describe the purpose of the shortcut. User agents MAY expose this information to assistive technology.

`url` member

The [=shortcut item’s=] member is a URL [=manifest/within scope=] of a [=Document/processed manifest=] that opens when the associated shortcut is activated.

`icons` member

The shortcut item’s member lists images that serve as iconic representations of the shortcut in various contexts.

When shortcut item shortcut having manifest is invoked, run the following steps:

Processing shortcut items

External application resource

Each represents an application related to the web application.

An [=external application resource=] can have the following members, some of which are required to be a [=valid external application resource=]:

A MUST have [=external application resource/platform=] member, and either an [=external application resource/url=] or an [=external application resource/id=] member (or both).

In the following example, the web application is listing two different related applications, one on Google Play Store and the other one on the iTunes Store. The one on the Google Play Store has an Android package name, a minimum version specifier, and cryptographic fingerprints used for verification, in a Play-Store-specific manner.

`platform` member

The member represents the [=platform=] this [=external application resource=] is associated with. A represents a software distribution ecosystem or possibly an operating system. This specification does not define the particular values for the platform member.

`url` member

An [=external application resource’s=] member is the URL where the application can be found.

`id` member

An [=external application resource’s=] member represents the id which is used to represent the application on the platform.

`min_version` member

An [=external application resource’s=] member represents the minimum version of the application that is considered related to this web app. This version is a string with platform-specific syntax and semantics.

`fingerprints` member

An [=external application resource’s=] member represents an [=list=] of [=fingerprints=].

Installable web applications

For example, on user agents that support installation, a web application could be presented and launched in a way that, to the end-user, is indistinguishable from native applications: such as appearing as a labeled icon on the home screen, launcher, or start menu. When launched, the manifest is applied by the user agent to the top-level browsing context prior to the start URL being loaded. This gives the user agent an opportunity to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, and again as an example, the user agent could install the web application into a list of bookmarks within the user agent itself.

Application’s name

The is derived from either the [=manifest/name=] member or [=manifest/short_name=] member.

When either the [=manifest/name=] member or the [=manifest/short_name=] member is missing, empty, or the wrong type, a user agent MAY use the [=manifest/name=] member as a fallback for the [=manifest/short_name=] member or [=manifest/short_name=] member as the fallback for the [=manifest/name=] member.

If the [=manifest/name=] and [=manifest/short_name=] members are missing, empty, or the wrong type, a user agent MAY fallback to the <> to find suitable replacements for missing manifest members (e.g., using `application-name` in place of [=manifest/name=] or [=manifest/short_name=]). Alternatively, the user agent SHOULD assign a default name (e.g., «Untitled») that follows platform conventions. Alternatively, a user agent MAY allow the end-user to input some text that can serve as the application’s name.

When both the [=manifest/name=] and [=manifest/short_name=] members are present, it is left up to implementations to decide which member is best suited for the space available (e.g., the [=manifest/short_name=] member might be better suited for the space available underneath an icon).

Privacy and security considerations

It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.

Uninstallation

User agents SHOULD provide a mechanism for the user to remove an installed web application application.

It is RECOMMENDED that at the time of removal, the user agent also present the user with an opportunity to revoke other persistent data and settings associated with the application, such as permissions and persistent storage.

Navigation scope

The is the «scope» item of a [=Document/processed manifest=]. The navigation scope restricts the set of URLs to which an [=application context=] can be [=navigated=] while the manifest is [=applied=].

If the [=manifest/scope=] member is not present in the manifest, it defaults to the parent path of the [=manifest/start_url=] member. For example, if [=manifest/start_url=] is `/pages/welcome.html`, and [=manifest/scope=] is missing, the navigation scope will be `/pages/` on the same origin. If [=manifest/start_url=] is `/pages/` (the trailing slash is important!), the navigation scope will be `/pages/`.

Developers should take care, if they rely on the default behavior, that all of the application’s page URLs begin with the parent path of the start URL. To be safe, explicitly specify [=manifest/scope=].

A [=URL=] |target:URL| is said to be of [=URL=] |scope:URL| if the following algorithm returns `true`:

A [=URL=] |target:URL| is of a |manifest:processed manifest| if the |target| is [=URL/within scope=] of |manifest|’s [=manifest/navigation scope=] (i.e., [=URL/within scope=] of |manifest|’s [=manifest/scope=] member).

The URL string matching in this algorithm is prefix-based rather than path-structural (e.g. a target URL string `/prefix-of/resource.html` will match an app with scope `/prefix`, even though the path segment name is not an exact match). This is intentional for consistency with Service Workers. To avoid unexpected behavior, use a scope ending in a `/`.

If the [=application context=]’s [=active document=]’s [=Document/URL=] is not [=manifest/within scope=] of the [=application context=]’s [=Document/processed manifest=], the user agent SHOULD show a prominent UI element indicating the [=Document/URL=] or at least its [=origin=], including whether it is served over a secure connection. This UI SHOULD differ from any UI used when the [=Document/URL=] is [=manifest/within scope=] of the [=application context=]’s [=Document/processed manifest=], in order to make it obvious that the user is navigating off scope.

Nothing prevents an application context from navigating to a URL that is outside of the manifest’s [=manifest/navigation scope=], while still having the manifest applied to it.

Unlike previous versions of this specification, user agents are no longer required or allowed to block off-scope navigations, or open them in a new top-level browsing context. This practice broke some sites that navigate to an off-scope URL (e.g., to perform third-party authentication). See Issue 646.

Security considerations

The above recommendation (to show some UI when the application context is navigated to an out-of-scope URL) is for security reasons. It ensures that users are always aware of which origin they are interacting with.

Despite this, there is still a potential spoofing risk, if an installed app pretends to navigate to an out-of-scope site on another origin. The site shows a fake version of the user agent’s prominent out-of-scope UI, indicating to the user that it is on another origin. However, in reality, the user has never navigated away from the installed app’s origin, and the user agent is not showing any out-of-scope UI. User agents could try to show the out-of-scope UI in a way that cannot be spoofed by the installed app. However, due to the nature of the user agent’s UI being minimal or non-existent for installed apps, this may not be possible.

Deep links

A is a URL that is [=manifest/within scope=] of an [=installed web application=]’s [=Document/processed manifest=].

An application context can be instantiated through a deep link, in which case, the manifest is applied and the deep link is loaded within the context of a web application.

The concept of a deep link is useful in that it allows hyperlinking from one installed web application to another. This can be from a native application to an installed web application and vice versa. Theoretically, this can provide seamless context switching between native and web applications through standard hyperlinks. And in the case where a particular web application is not installed, the OS can just open the link in the user’s preferred web browser.

Implementers are encouraged make such context switching obvious to the user, for example, by adhering to the human interface guidelines of the underlying platform with respect to application switching.

Choosing a display mode

A [=display mode=], as defined in [[MEDIAQUERIES-5]], represents how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.). Display modes correspond to user interface (UI) metaphors and functionality in use on a given platform.

Once a user agent [=applies=] a particular display mode to an application context, it becomes the for the top-level browsing context (i.e., it is used as the display mode when the window is navigated). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode.

When the [=manifest/display=] member is missing, or if there is no valid [=manifest/display=] member, the user agent uses the [=display mode/browser=] display mode as the default display mode. As such, the user agent MUST support the [=display mode/browser=] display mode.

The is given by the following algorithm. The algorithm takes a [=Document/processed manifest=] |manifest:processed manifest| and returns a [=display mode=].

The above loop is guaranteed to return a value before the assertion, due to the fact that [=display mode/browser=] is in every mode’s [=fallback chain=], and the requirement that all user agents support the [=display mode/browser=] [=display mode=].

SuperSecure Browser (a fictitious browser) only supports the `minimal-ui` and `browser` display modes, but a developer declares that they wants `fullscreen` in the manifest by using the [=manifest/display=] property. In this case, the user agent will first check if it supports `fullscreen` (it doesn’t), so it falls back to `standalone` (which it also doesn’t support), and ultimately falls back to `minimal-ui`.

The is the [=list=] « «[=display mode/fullscreen=]», «[=display mode/standalone=]», «[=display mode/minimal-ui=]», «[=display mode/browser=]» ».

A user agent MUST reflect the applied display mode of the web application in the ‘`display-mode`’ media feature [[MEDIAQUERIES-5]].

A user agent will expose the ‘`display-mode`’ media feature irrespective of whether a manifest is being applied to a browsing context. For example, if the end-user puts the application into fullscreen, then the user agent would reflect this change to CSS and scripts via the ‘`display-mode`’ media feature.

Privacy and security considerations

This specification does not directly deal with high-value data. However, installed web applications and their data could be seen as «high value» (particularly from a privacy perspective).

As the manifest format is JSON and will commonly be encoded using [[UNICODE]], the security considerations described in [[JSON]] and [[UNICODE-SECURITY]] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest, implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [[CSS-MIME]], [[ECMAScript-MIME]], [[HTML]].

As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.

As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [[URL]] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [[UNICODE-SECURITY]].

Developers need to be aware of the security considerations discussed throughout the [[CSP3]] specification, particularly in relation to making `data:` a valid source for the purpose of inlining a manifest. Doing so can enable XSS attacks by allowing a manifest to be included directly in the document itself; this is best avoided completely.

It is RECOMMENDED that UI that affords the end user the ability to install a web application also allows inspecting the icon, name, start URL, origin, etc. pertaining to a web application. This is to give an end-user an opportunity to make a conscious decision to approve, and possibly modify, the information pertaining to the web application before installing it. This also gives the end-user an opportunity to discern if the web application is spoofing another web application, by, for example, using an unexpected icon or name.

It’s conceivable that a shortcut [=shortcut item/url=] could be crafted to indicate that the application was launched from outside the browser (e.g., `»url»: «/task/?from=homescreen»`). It is also conceivable that developers could encode strings into the [=shortcut item/url=] that uniquely identify the user (e.g., a server assigned UUID ). This is fingerprinting/privacy sensitive information that the user might not be aware of.

When the web application is running, it is RECOMMENDED that the user agent provides the end-user a means to access common information about the web application, such as the origin, start and/or current URL, granted permissions, and associated icon. How such information is exposed to end-users is left up to implementers.

Additionally, when applying a manifest that sets the display mode to anything except «[=display mode/browser=]», it is RECOMMENDED that the user agent clearly indicate to the end-user that their are leaving the normal browsing context of a web browser. Ideally, launching or switching to a web application is performed in a manner that is consistent with launching or switching to other applications in the host platform. For example, a long and obvious animated transition, or speaking the text «Launching application X».

The `display` member allows an origin some measure of control over a user agent’s native UI. After taking over the full screen, it could attempt to mimic the user interface of another application. This is also facilitated by the `’display-mode’` media feature [[MEDIAQUERIES-5]], through which a script can know the display mode of a web application.

IANA considerations

Media type registration

If the protocol over which the manifest is transferred supports the [[MIME-TYPES]] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the [=application manifest media type=].

Link relation type registration

There is only one class of product that can claim conformance to this specification: a [=user agent=].

Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner. For instance, search engines, or crawlers, could find and process manifests to build up catalogs of sites that potentially work as installable web applications.

Extensibility

This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the [=application manifest/processing extension-point=] to hook into the steps for processing a manifest. Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.

To allow the community to easily find extensions, please add your extensions to the Extensions Registry.

When specifying a new member, don’t override or monkey patch anything defined in this specification. Also, don’t assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.

If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.

Proprietary manifest members

Although proprietary extensions are undesirable, they can’t realistically be avoided. As such, the RECOMMENDED way to add a new proprietary manifest member as an extension is to use a vendor prefix.

We encourage implementors to add proprietary extensions to our Extensions Registry. This allows the community to track what extensions vendors and/or the web community have defined and documented. Periodically, we will consider those extensions for standardization.

The following is an example of three hypothetical vendor extensions.

Incubations

Application Information

Several members of the Web App Manifest provide additional metadata related to how the web application may be presented in the context of a digital storefront, installation dialog, or other surfaces where the web application may be marketed or distributed. In an effort to support these use cases better, the following members have been moved into [[[manifest-app-info]]]:

Relationship to HTML’s `link` and `meta` elements

An extensive discussion of why we chose to use JSON instead of HTML `meta`/`link` tags for this specification is available on GitHub and on the www-tag list. Below is a short summary of the key points raised in those discussions.

The document format defined in this specification provides a unified means of encapsulating metadata about a Web application in a way that we hope will avoid existing pitfalls with both proprietary and [[HTML]]’s `meta`/`link` tags. Those pitfalls include:

Although it would be unrealistic to think that this specification won’t bring its own set of problems, externalizing this data in the form of a manifest solves the problems described above. These problems are solved by:

Lastly, this specification does not make the standardized solutions found in [[HTML]] redundant. When members like the `name` or `icons` is missing from the manifest, user agents can search in a manifest’s owner [[HTML]] document for things like icons and the application name (or a user agent might even fallback to proprietary tags/metadata, if they are present in a document).

JSON Schema

Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org. It is licensed under Apache 2.0. It is kindly maintained by Mads Kristensen. If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.

Internationalization

It is expected that authors will localize the content of a manifest by using one of the following options:

Dynamically setting the language: This can include, for instance, asking the end-user what their preferred language is and dynamically adding or replacing the manifest link relationship to the document based on that language preference (e.g., using a URL like «manifest.php?lang=fr»). Using content-negotiation, or geotargeting, etc. on the server: The server that hosts the web application could attempt to predetermine the end-user’s language by using geotargeting or by using content negotiation (e.g., using [[RFC7540]]’s «`Accept-Language`» header, or even a custom HTTP header).

Given the options above, developers need to be mindful of the end-user’s privacy with respect to their preferred language: When the end-user has explicitly indicated their language preference to a web application (i.e., when not just using the user-agent default language settings), sending the end-user’s preferred language in the clear over the wire is generally not OK. Doing so would reveal personal information about an end-user. As such, developers are encouraged to use [[TLS]] to reduce the chances of pervasive monitoring of their Web applications [[RFC7258]].

Use Cases and Requirements

Change log

The following are some significant changes that were made since First Public Working Draft:

Acknowledgements

This document reuses text from the [[HTML]] specification, as permitted by the license of that specification.

Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.

Claudio Gomboli for icon example images.

Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.

Источник