Installing a webapp can come from a variety of channels. This section serves to enumerate them all and show how they fit together in the installation pipeline.
Here is a graphic of the installation flow:
https://tinyurl.com/dpwa-installation-flowchart
Note: The ExternallyManagedAppManager adds a few steps before this, and will sometimes (for placeholder apps) build a custom WebAppInstallInfo object to skip the ‘build’ steps.
There are a variety of commands used to install web apps. If introducing a new installation source, consider making a new command to isolate your operation (and prevent it from being complicated by other use-cases).
There are a variety of installation sources and expectations tied to those sources.
User-initiated installation. To make the omnibox install icon visible, the document must: Be promotable and installable. NOT be inside of the scope of an installed WebApp with an effective display mode display mode that isn't kBrowser.
Triggers an install view that will show the name & icon to the user to confirm install. If the manifest also includes screenshots with a wide form-factor, then a more detailed install dialog will be shown.
This uses the FetchManifestAndInstallCommand, providing just the WebContents of the installable page.
Fails if, after the user clicks : After clicking on the install icon, the WebContents is no longer promotable, skipping engagement checks. The user rejects the installation dialog.
User-initiated installation. To make the install menu option visible, the document must: Be promotable and installable. NOT be inside of the scope of an installed WebApp with an effective display mode display mode that isn't kBrowser.
Triggers an install view that will show the name & icon to the user to confirm install. If the manifest also includes screenshots with a wide form-factor, then a more detailed install dialog will be shown.
Calls FetchManifestAndInstallCommand with the WebContents of the installable page, and fallback_behavior = FallbackBehavior::kUseFallbackInfoWhenNotInstallable.
Fails if: The user rejects the installation dialog.
Notably, this option does not go through the same exact pathway as the omnibox install icon, as it shares the call-site as the “Create Shortcut” method below. The main functional difference here is that if the site becomes no longer promotable in between clicking on the menu option and the install actually happening, it will not fail and instead fall back to a fake manifest and/or fake icons based on the favicon. Practically, this option doesn't show up if the site is not promotable. Should it share installation pathways as the the omnibox install icon? Probably, yes.
User-initiated installation. This menu option is always available, except for internal chrome urls like chrome://settings.
Prompts the user whether the shortcut should “open in a window”. If the user checks this option, then the resulting WebApp will have the user display set to kStandalone / open-in-a-window.
The document does not need to have a manifest for this install path to work. If no manifest is found, then a fake one is created with start_url equal to the document url, name equal to the document title, and the icons are generated from the favicon (if present).
Calls FetchManifestAndInstallCommand with the WebContents of the installable page, and fallback_behavior = FallbackBehavior::kAllowFallbackDataAlways.
Fails if: The user rejects the shortcut creation dialog.
These installations are more customizable than user installations, as these external app management surfaces need to specify all of the options up front (e.g. create shortcut on desktop, open in window, run on login, etc). The ExternalAppResolutionCommand is used for this purpose.
The general installation flow of an externally managed app is:
ExternallyManagedAppProvider::SynchronizeInstalledAppsExternalAppResolutionCommand for each app to start resolving what the final behavior should be.InstallPlaceholderJob is used to install a placeholder app.These placeholder apps are not meant to stay, and to replace them with the intended apps, the following occurs:
ExternalAppResolutionCommand is given the ID of the existing placeholder app.When an app is installed via sync on a non-ChromeOS device, it is initially installed in a “suggested” state (InstallState::SUGGESTED_FROM_ANOTHER_DEVICE) without full OS integration. See Installation State in the concepts doc for more details. On ChromeOS, synced apps are always fully installed with OS integration.
Sync installs have a few extra complications:
Due to this, unlike other installs, a special WebApp::is_from_sync_and_pending_installation (protobuf variable is saved in the database. WebApps with this set to true are treated as not fully installed, and are often left out of app listings. This variable is reset back to false when the app is finished installing.
To handle the cases above, on startup when the database is loaded, any WebApp with is_from_sync_and_pending_installation of true will be re-installed inside of WebAppSyncBridge::MaybeInstallAppsFromSyncAndPendingInstallation
On non-ChromeOS devices, an app can be in a “suggested” state (e.g. from sync) or “installed without OS integration” (e.g. preinstalled). To trigger a full installation with OS integration, the user can:
chrome://apps and select “Install”.Programmatically, this is handled by the InstallAppLocallyCommand.
On non-ChromeOS devices, an app can be not locally installed. To become locally installed, the user can follow a normal install method (the install icon will show up), or they can interact with the app on chrome://apps.
The chrome://apps code is unique here, and instead of re-installing the app, it schedules an InstallAppLocallyCommand to set the app as locally installed and trigger OS integration.
Similarly to above, in chrome://apps the user can “Create Shortcuts...” for a web app. This should overwrite any shortcuts already created, and basically triggers OS integration to install shortcuts again via an OsIntegrationSynchronizeCommand.