Web App Manifest - Application Information

W3C Group Note

More details about this document
This version:
https://www.w3.org/TR/2023/NOTE-manifest-app-info-20230821/
Latest published version:
https://www.w3.org/TR/manifest-app-info/
Latest editor's draft:
https://w3c.github.io/manifest-app-info/
History:
https://www.w3.org/standards/history/manifest-app-info/
Commit history
Editor:
Aaron Gustafson (Microsoft Corporation)
Feedback:
GitHub w3c/manifest-app-info (pull requests, new issue, open issues)

Abstract

This document is a registry of supplementary members for the Web Application Manifest specification that provide additional metadata to an application manifest. This metadata can be used in a digital storefront or other surfaces where this web application may be marketed or distributed, or to enhance an installation dialog when installing a web application.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This is document is constantly evolving and we publish new snapshots every time we commit a change. Interested parties can subscribe to changes or even propose new manifest members in the manifest-app-info GitHub repository.

This document was published by the Web Applications Working Group as a Group Note using the Note track.

This Group Note is endorsed by the Web Applications Working Group, but is not endorsed by W3C itself nor its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The W3C Patent Policy does not carry any licensing requirements or commitments on this document.

This document is governed by the 12 June 2023 W3C Process Document.

1. Marketable web applications

As web applications become available via more services (e.g., digital storefronts, search results) where they are presented alongside native applications, it becomes quite important for them to appear similarly to their native counterparts. A web application can define both its name and icons in the manifest, but those keys do not provide enough information to help users determine whether they might want to install it. Users have become accustomed to being offered more details about the applications they consider installing, and this document defines additional manifest members that can provide that.

2. Supplementary manifest members

The following members supplement the members of an application manifest. These members are classified as supplementary because they are not applied to a web application at runtime (i.e., they are purely advisory and don't affect how a user agent presents an installed web application). All members are all optional and can be added at the root of an application manifest, as shown in the following example.

Example 1: Using the supplementary members
{
  "name": "Donate App",
  "categories": ["fundraising", "donations"],
  "description": "This app helps you donate to worthy causes.",
  "iarc_rating_id": "e84b072d-71b3-4d3e-86ae-31a8ce4e53b7",
  "screenshots": [{
    "src": "images/screenshot.png",
    "sizes": "800x600",
    "platform": "windows",
    "label": "Lots of organizations to donate to"
  }]
}

As the application manifest is JSON, the members of this specification are of the types object, array, and string as defined in The JSON Data Interchange Format, 2nd edition.

2.1 categories member

The categories member is an array of strings that describes the application categories to which the web application belongs. It is meant as a hint to catalogs or stores listing web applications and it is expected that these will make a best effort to find appropriate categories (or category) under which to list the web application. Like search engines and meta keywords, catalogs and stores are not required to honor this hint.

Manifest authors are encouraged to use lower-case.

List of known categories:

Note: Adding more categories

If you'd like to add additional categories, please file a bug or send a pull request to the manifest-app-info GitHub repository.

2.2 description member

The description member is a string that allows the developer to describe the purpose of the web application. It serves as the accessible description of an installed web application.

2.3 iarc_rating_id member

The iarc_rating_id member is a string that represents the International Age Rating Coalition (IARC) certification code of the web application. It is intended to be used to determine which ages the web application is appropriate for.

Note

An IARC certificate can be obtained via participating storefronts, intended to be used for distributing the web app. The iarc_rating_id member only takes a single certification code. The same code can be shared across participating storefronts, as long as the distributed product remains the same (i.e., doesn’t serve totally different code paths depending on user agent sniffing and the like) and the other storefronts support it.

More information on the IARC can be found at: How IARC Works and How developers can get their games and apps rated with IARC.

2.4 screenshots member

The screenshots member is an array of screenshots objects, representing the web application in common usage scenarios.

3. Screenshot object and its members

A screenshots object is a ImageResource object with some additional members as defined below.

3.1 label member

The label member is a string that serves as the accessible name of that screenshots object. For accessibility, authors are encouraged to provide a label for each screenshot. This member can serve as alternative text for the rendered screenshot.

Example 2: Using the supplementary members
{
  "screenshots": [{
    "src": "images/screenshot.png",
    "sizes": "800x600",
    "form_factor": "wide",
    "label": "With Software, you can select a part of your screen and take a screenshot in seconds."
  }]
}

3.2 platform member

The platform member is a string that represents the distribution platform for which a given screenshot applies. Authors are encouraged to only use this member when the screenshot is only applicable in a specific context.

Note: Platform usage guidance for authors

Authors should only use platform for instances where a screenshot is not representative of a universal experience. For instance, an OS-specific platform designation should be reserved for instances where the screenshot includes functionality only available on that specific platform.

User agents might show as many (or as few) screenshots as they choose, but shouldn't display screenshots that do not pertain to their platform (e.g., Google Play should not show iOS-specific screenshots).

When no platform is set, user agents should assume the screenshot is applicable to all platforms.

User agents can use a screenshot’s aspect ratio (sizes) in determining if the screenshot should be displayed.

List of platform values that are specific to an operating system:

android
For Google Android.
chromeos
For Google ChromeOS.
ipados
For Apple iPadOS.
ios
For Apple iOS.
kaios
For KaiOS.
macos
For Apple macOS.
windows
For Microsoft Windows.
xbox
For Microsoft Xbox.

List of platform values aligned with application distribution platforms:

chrome_web_store
Google Chrome Web Store
play
Google Play Store
itunes
iTunes App Store
microsoft-inbox
Pre-installed with Microsoft Windows
microsoft-store
Microsoft Store
Note: Adding more categories

If you'd like to add additional platform, please file a bug or send a pull request to the manifest-app-info GitHub repository.

3.3 form_factor member

The form_factor member is a string that represents the screen shape of a broad class of devices for which a given screenshot applies. Authors are encouraged to only use this member when the screenshot is only applicable in a specific context.

Note: form_factor usage guidance for authors

Authors should only use form_factor for instances where a screenshot is not representative of a universal experience. For instance, if the layout/design differs based on the screen orientation, setting "narrow" or "wide" is advisable.

User agents might show as many (or as few) screenshots as they choose, but shouldn't display screenshots that do not pertain to their form factor (e.g., mobile phones shouldn't show "wide" form_factor screenshots).

When no form_factor is set, user agents should assume the screenshot is applicable to all form factors.

List of form_factor values:

narrow
For screenshots applicable to narrow screens only (e.g., mobile devices).
wide
For screenshots applicable to wide screens only (e.g., status boards).

A. Internationalization

This section is non-normative.

It is expected that authors will localize the content of all text strings defined in this document based on the approach(es) outlined in the Manifest spec.

B. Acknowledgements

Rob Dolin for spearheading a lot of this work, specially the iarc_rating_id member, and Kenneth Rohde Christiansen for helping to vet these ideas.

We'd also like to thank the following contributors: Christian Liebel, Julien Cayzac, Marcos Cáceres, Thomas Steiner, Xiaoqian Wu, and Yajing Tang.

C. Index

C.1 Terms defined by this specification

C.2 Terms defined by reference

D. References

D.1 Informative references

[accname-1.2]
Accessible Name and Description Computation 1.2. Bryan Garaventa; Joanmarie Diggs; Michael Cooper. W3C. 11 July 2019. W3C Working Draft. URL: https://www.w3.org/TR/accname-1.2/
[appmanifest]
Web Application Manifest. Marcos Caceres; Kenneth Christiansen; Matt Giuca; Aaron Gustafson; Daniel Murphy; Anssi Kostiainen. W3C. 2 May 2023. W3C Working Draft. URL: https://www.w3.org/TR/appmanifest/
[ECMA-404]
The JSON Data Interchange Format, 2nd edition. Ecma International. 1 December 2017. Standard. URL: https://www.ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf
[image-resource]
Image Resource. Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 4 June 2021. W3C Working Draft. URL: https://www.w3.org/TR/image-resource/