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 use_fallback = true.
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 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 use_fallback = true.
Fails if: The user rejects the shortcut creation dialog.
Checks promotability before installing, skipping engagement and serviceworker checks
Calls [WebAppInstallManager::InstallWebAppFromManifest][12], providing just the WebContents of the installable page.
TODO: Document when this API is called & why.
There are a number of apps that are managed externally. This means that there is an external manager keeps it's own list of web apps that need to be installed for a given external install source.
See the web_app::ExternalInstallSource enum to see all types of externally managed apps. Each source type should have an associated “manager” that gives the list of apps to ExternallyManagedAppProvider::SynchronizeInstalledApps.
These installations are 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). Thus the ExternallyManagedInstallCommand is called here, with the params generated by web_app::ConvertExternalInstallOptionsToParams.
The general installation flow of an externally managed app is:
ExternallyManagedAppProvider::SynchronizeInstalledAppsExternalAppResolutionCommand for each app to start resolving what the final behavior should be.ExternallyManagedInstallCommand, and continue installation on the normal pipeline (described above, and flowchart above).start_url as the document url, and name as the document titleThese placeholder apps are not meant to stay, and to replace them with the intended apps, the following occurs:
WebAppInstallManager::InstallWebAppWithParams.When the sync system receives an WebApp to install, it uses the InstallFromSyncCommand`. One major difference is if the installation fails for any reason (manifest is invalid or fails to load, etc), then a backup installation happens using information from the icon urls from the sync data, and document/favicons if available.
If the platform is not ChromeOS, then the app will not become locally installed. This means that OS integration will not be triggered, no platform shortcuts created, etc. 1. If the platform is ChromeOS, it will become locally installed, and all OS integrations will be triggered (just like a normal user-initiated install.)
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 not locally installed. To become locally installed, the user can follow a normal install method (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, in manually sets the locally_installed bit to true in AppLauncherHandler::HandleInstallAppLocally, and triggers OS integration in AppLauncherHandler::InstallOsHooks
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 in AppLauncherHandler::HandleCreateAppShortcut