chrome/browser/web_applications/docs/concepts.md
In addition to the universal web app concepts, there are several concepts specific to desktop web apps and the WebAppProvider system.
In addition to the developer-specified display (see Display Mode), the user can specify how they want a WebApp to be displayed, with the only option being whether to "open in a window" or not. Internally, this is expressed in the same display mode enumeration type, but only the kStandalone and kBrowser values are used to specify "open in a window" and "do not open in a window", respectively.
The pseudocode to determine the ACTUAL display mode a WebApp is displayed in is:
if (user_display_mode == kStandalone)
return developer_specified_display_mode;
else
return kBrowser; // Open in a tab.
This refers to the user specifying that a WebApp should open in the developer specified display mode.
This refers to the user specifying that a WebApp should NOT open in a window, and thus the WebApp, if launched, will just be opened in a browser tab.
Each app has one or more 'management source', specified by the WebAppManagement::Type enumeration. This signifies the system that is 'managing' the install, AKA responsible for installing or uninstalling the app. Internally, the web app system will ensure that the app will only be uninstalled if there are no sources left in the app.
When a user installs an app, the kSync management source is specified, because user installs are considered 'managed' by the sync system (and installs will by synced to all devices). See the WebAppManagement enumeration for the description of other management sources.
Installation by certain sources can cause the app to no longer be "uninstallable" by the user. The method CanUserUninstallWebApp function determines if this is the case.
There are some webapps which are managed by external sources - for example, the enterprise policy force-install apps, or the system web apps for ChromeOS. These are generally not installed by user interaction, and the WebAppProvider needs to install something for each of these apps.
Sometimes, the installation of these apps can fail because the install url is not reachable (usually a cert or login needs to occur, and the url is redirected). When this happens, the system can install a "placeholder" app, which is a fake application that, when launched, navigates to the install url of the application, given by the external app manager.
To resolve placeholder apps back into the intended installation, another external
install is triggered for the same install URL. The
ExternalAppResolutionCommand is given the ID of the existing
placeholder app. After the new app is successfully installed, the
placeholder app is uninstalled.
A web app can exist in several different installation states, which determine
its capabilities and how it's presented to the user. These states are
represented internally by the InstallState enum.
Suggested from another device: The app is installed on another one of
the user's devices and has been synced to the current device, but it
hasn't been fully installed yet. These apps appear in chrome://apps (often
grayed out) but don't have OS integrations like shortcuts or protocol
handlers. They cannot be launched in a standalone window until they are
fully installed. This state corresponds to
InstallState::SUGGESTED_FROM_ANOTHER_DEVICE.
Installed without OS integration: The app is installed on the device,
but without any OS-level integrations. This is common for pre-installed
apps on non-ChromeOS platforms. Like suggested apps, they cannot be
launched in a standalone window until OS integration is enabled. This state
corresponds to InstallState::INSTALLED_WITHOUT_OS_INTEGRATION.
Installed with OS integration: The app is fully installed and
integrated with the operating system. This includes shortcuts, protocol
handling, file handling, and the ability to run on OS login. This is the
state for user-installed apps or apps that have had their OS integration
explicitly triggered. This state corresponds to
InstallState::INSTALLED_WITH_OS_INTEGRATION.
To query for apps with specific capabilities, which often depend on their
installation state, the WebAppFilter class should be used.
For example, WebAppFilter::IsSuggestedApp() can be used to find apps that are
suggested from another device.
For an app that is only "suggested" or "installed without OS integration", a full installation with OS integration can be triggered by:
chrome://apps and selecting "Install".InstallAppLocallyCommand.This was designed this way because on non-ChromeOS devices, it was considered a bad user experience to fully install all of a user's synced web apps (creating platform shortcuts, etc.), as this might not be expected by the user on a new device.