Google Git
Sign in
chromium / codesearch / chromium / src / refs/heads/master-original / . / chrome / browser / web_applications
tree: 7f34ed0eaa6893481cf2297fa5830e00efbbd3e8 [path history] [tgz]
  1. app_service/
  2. chrome_pwa_launcher/
  3. components/
  4. docs/
  5. extensions/
  6. policy/
  7. preinstalled_web_apps/
  8. proto/
  9. system_web_apps/
  10. test/
  11. BUILD.gn
  12. daily_metrics_helper.cc
  13. daily_metrics_helper.h
  14. daily_metrics_helper_unittest.cc
  15. DIR_METADATA
  16. extension_status_utils.h
  17. externally_managed_app_install_task.cc
  18. externally_managed_app_install_task.h
  19. externally_managed_app_manager_impl.cc
  20. externally_managed_app_manager_impl.h
  21. externally_managed_app_manager_impl_browsertest.cc
  22. externally_managed_app_manager_impl_unittest.cc
  23. externally_managed_app_registration_task.cc
  24. externally_managed_app_registration_task.h
  25. file_utils_wrapper.cc
  26. file_utils_wrapper.h
  27. manifest_update_manager.cc
  28. manifest_update_manager.h
  29. manifest_update_manager_browsertest.cc
  30. manifest_update_task.cc
  31. manifest_update_task.h
  32. manifest_update_task_unittest.cc
  33. OWNERS
  34. preinstalled_web_app_manager.cc
  35. preinstalled_web_app_manager.h
  36. preinstalled_web_app_manager_browsertest.cc
  37. preinstalled_web_app_manager_unittest.cc
  38. preinstalled_web_app_migration_browsertest.cc
  39. preinstalled_web_app_utils.cc
  40. preinstalled_web_app_utils.h
  41. preinstalled_web_app_utils_unittest.cc
  42. preinstalled_web_apps_browsertest.cc
  43. README.md
  44. UI_OWNERS
  45. web_app.cc
  46. web_app.h
  47. web_app_audio_focus_browsertest.cc
  48. web_app_database.cc
  49. web_app_database.h
  50. web_app_database_factory.cc
  51. web_app_database_factory.h
  52. web_app_database_unittest.cc
  53. web_app_file_handler_manager.cc
  54. web_app_file_handler_manager.h
  55. web_app_icon_manager.cc
  56. web_app_icon_manager.h
  57. web_app_icon_manager_browsertest.cc
  58. web_app_icon_manager_unittest.cc
  59. web_app_install_finalizer.cc
  60. web_app_install_finalizer.h
  61. web_app_install_manager.cc
  62. web_app_install_manager.h
  63. web_app_install_manager_unittest.cc
  64. web_app_install_task.cc
  65. web_app_install_task.h
  66. web_app_install_task_unittest.cc
  67. web_app_installation_utils.cc
  68. web_app_installation_utils.h
  69. web_app_installation_utils_unittest.cc
  70. web_app_mover.cc
  71. web_app_mover.h
  72. web_app_mover_browsertest.cc
  73. web_app_mover_unittest.cc
  74. web_app_proto_utils.cc
  75. web_app_proto_utils.h
  76. web_app_proto_utils_unittest.cc
  77. web_app_protocol_handler_manager.cc
  78. web_app_protocol_handler_manager.h
  79. web_app_provider.cc
  80. web_app_provider.h
  81. web_app_provider_factory.cc
  82. web_app_provider_factory.h
  83. web_app_registrar.cc
  84. web_app_registrar.h
  85. web_app_registrar_unittest.cc
  86. web_app_registry_update.cc
  87. web_app_registry_update.h
  88. web_app_shortcut_manager.cc
  89. web_app_shortcut_manager.h
  90. web_app_sync_bridge.cc
  91. web_app_sync_bridge.h
  92. web_app_sync_bridge_unittest.cc
  93. web_app_sync_install_delegate.h
  94. web_app_tab_helper.cc
  95. web_app_tab_helper.h
  96. web_app_unittest.cc
chrome/browser/web_applications/README.md

Web Apps

This directory holds the core of Chromium's web app system. For a quick code starting point see WebAppProvider::Start(), this is the entry point where everything web app related begins.

What are web apps?

Simply put web apps are sites that the user installs onto their machine mimicking a native app install on their respective operating system.

User entry points

Sites that meet our install promotion requirements will have an install prompt appear in the omnibox on the right.

Users can see all of their web apps on chrome://apps (viewable on non-ChromeOS).

Developer interface

Sites customise how their installed site integrates at the OS level using a web app manifest. See developer guides for in depth overviews:

Terms & Phrases

Manifest, or WebManifest

This refers to the the document described by the appmanifest spec, with some extra features described by manifest-incubations. This document describes metadata and developer configuration of an installable webapp.

For code representations of the manifest see the list.

Manifest Link

A manifest link is something that looks like this in a html document:

<link rel="manifest" href="manifest.webmanifest">

This link ties the manifest to the document, and subsequently used in the spec algorithms defined in appmanifest or manifest-incubations to describe the webapp and determine if it is installable.

Installable

If a document or page is considered “installable”, then the user agent can create some form of installed web app for that page. To be installable, web_app::CanCreateWebApp must return true, where:

  • The user profile must allow webapps to be installed
  • The web contents of the page must not be crashed
  • The last navigation on the web contents must not be an error (like a 404)
  • The url must be http, https, or chrome-extension

This is different than promotable below, which determines if Chrome will promote installation of the page.

Promotable

A document is considered “promotable” if it fulfils a set of criteria. This criteria may change to further encourage a better user experience for installable web apps. There are also a few optional checks that depend on the promotability checker. This general criteria as of 2021/04/20:

  • The document contains a manifest link.
  • The linked manifest can be processed according to the spec and is valid.
  • The processed manifest contains the fields:
    • name
    • start_url
    • icons with at least one icon with a valid response that is a parsable image.
    • display field that is not "browser"
  • “Serviceworker check”: The start_url is ‘controlled’ (can be served by) a serviceworker. Optionally turned off
  • “Engagement check”: The user has engaged with, or interacted with, the page or origin a certain amount (currently at least one click and some seconds on the site). Optionally turned off

Notes:

  • Per spec, the document origin and the start_url origin must match.
  • Per spec, the start_url origin does not have to match the manifest_url origin
  • The start_url could be different than the document_url.

Scope

Scope refers to the prefix that a WebApp controls. All paths at or nested inside of a WebApp's scope is thought of as “controlled” or “in-scope” of that WebApp. This is a simple string prefix match. For example, if scope is /my-app, then the following will be “in-scope”:

  • /my-app/index.html
  • /my-app/sub/dir/hello.html
  • /my-app-still-prefixed/index.html (Note: if the scope was /my-app/, then this would not be out-of-scope)

And the following will “out-of-scope”:

  • /my-other-app/index.html
  • /index.html

Display Mode

The display of a webapp determines how the developer would like the app to look like to the user. See the spec for how the display member is processed in the manifest and what the display modes mean.

User Display Mode

In addition to the developer-specified display, 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 as display, but only the kStandalone and kBrowser values are used to specify “open in a window” and “do not open in a window”, respectively.

Effective Display Mode

The psuedocode to determine the ACTUAL display mode a WebApp is displayed is:

if (user_display_mode == kStandalone)
  return developer_specified_display_mode;
else
  return kBrowser; // Open in a tab.

Open-in-window

This refers to the user specifying that a WebApp should open in the developer specified display mode.

Open-in-browser-tab

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.

Placeholder app

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.

When any web contents, either in-(placeholder)-app or in the browser, successfully navigates to a install url that the placeholder app is installed for, the web app installation is restarted for the true app, and after that installation succeeds the placeholder app is uninstalled.

Locally Installed

When signing into a non-ChromeOS device, all web apps are installed but not locally installed. This means that OS integration is not triggered (so there are no platform shortcuts created), install icons will still show up for the app websites, and the app icon will appear greyed out on chrome://apps.

For an app to become locally installed, the user must do one of the following:

  • Navigate to chrome://apps, find the greyed-out icon of the app, right click on it, and select “Install”.
  • Follow any of the normal installation routes to install that app (e.g. visit the app page in the browser and interact with the omnibox install icon)

This was done because on non-ChromeOS devices it was considered a bad user experience to fully install all of the profile's web apps (creating platform shortcuts, etc), as this might not be expected by the user.

What makes up Chromium's implementation?

The task of turning web sites into “apps” in the user's OS environment has many parts to it. Before going into the parts, here is where they live:

  • The WebAppProvider core system lives on the Profile object.
  • The WebAppUiManagerImpl also lives on the Profile object (to avoid deps issues).
  • The AppBrowserController (typically WebAppBrowserController for our interests) lives on the Browser object.
  • The WebAppTabHelperBase lives on the WebContents object.

While most on-disk storage is done in the WebAppSyncBridge, the system also sometimes uses the PrefService. Most of these prefs live on the Profile (profile->GetPrefs()), but some prefs are in the global browser prefs (g_browser_process->local_state()). See the storage section below for more info.

There is a presentation that also goes over the class structure and dependency diagram here, but it may be out of date.

Here is more info for some (but not all) of the key parts:

WebAppProvider

This is a per-profile object housing all the various web app subsystems. This is the “main()” of the web app implementation where everything starts.

WebApp

This is the representation of an installed web app in RAM. Its member fields largely reflect all the ways a site can configure their web app manifest plus miscellaneous internal bookkeeping and user settings.

WebAppRegistrar

This is where all the WebApps live in memory and what many other subsystems query to look up any given web app's fields. Mutations to the registry have to go via WebAppSyncBridge.

Why is it full of GetAppXYZ() getters for every field instead of just returning a WebApp reference? Because web apps used to be backed by Extensions and in that mode there were no WebApps; instead everything was stored on an Extension.

WebAppSyncBridge

This is “bridge” between the WebAppProvider system‘s in-memory representation of web apps and the sync system’s database representation (along with sync system functionality like add/remove/modify operations). This integration is a little complex and deserves it's own document, but it basically:

  • Stores all WebApps into a database and updates the database if any fields change.
  • Updates the system when there are changes from the sync system.
    • Installs new apps, uninstalls apps the user uninstalled elsewhere, updates metadata like user display mode preference, etc.
  • Tells the sync system if there are local changes (installs, uninstalls, etc).

There is also a slide in a presentation here which illustrates how this system works, but it may be out of date.

Note: This only stores per-web-app data, and that data will be deleted if the web app is uninstalled. To store data that persists after uninstall, or applies to a more general scope than a single web app, then the PrefService can be used, either on the Profile object (per-profile data, profile->GetPrefs()) or on the browser process (g_browser_process->local_state()). Example of needing prefs:

  • Storing if an app was previously installed as a preinstalled app in the past.
  • Information is needed during chrome startup before profiles are loaded.
  • A feature needs to store global data - e.g. “When was the last time we showed the in-product-help banner for any webapp?”

WebAppInstallManager

This is where web apps are created, updated and removed. The install manager spawns WebAppInstallTasks for each “job”.

Installation comes in many different forms from a simple “here's all the info necessary please install it” to “please install the site currently loaded in this web contents and fetch all the manifest data it specifies” with a few inbetweens.

ExternallyManagedAppManager

This is for all installs that are not initiated by the user. This includes preinstalled apps, policy installed apps and system web apps.

These all specify a set of install URLs which the ExternallyManagedAppManager synchronises the set of currently installed web apps with.

WebAppInstallFinalizer

This is the tail end of the installation process where we write all our web app metadata to disk and deploy OS integrations (like desktop shortcuts and file handlers) using the OsIntegrationManager.

This also manages the uninstallation process.

WebAppUiManager

Sometimes we need to query window state from chrome/browser/ui land even though our BUILD.gn targets disallow this as it would be a circular dependency. This abstract class + impl injects the dependency at link time (see WebAppUiManager::Create()'s declaration and definition locations).

Storage

TODO

Deep Dives

Testing

See the testing docs.

Debugging

Use chrome://internals/web-app to inspect internal web app state.