diff options
Diffstat (limited to 'browser/docs')
| -rw-r--r-- | browser/docs/BrowserUsageTelemetry.rst | 148 | ||||
| -rw-r--r-- | browser/docs/CommandLineParameters.rst | 29 | ||||
| -rw-r--r-- | browser/docs/index.rst | 33 | ||||
| -rw-r--r-- | browser/docs/overview.rst | 105 |
4 files changed, 315 insertions, 0 deletions
diff --git a/browser/docs/BrowserUsageTelemetry.rst b/browser/docs/BrowserUsageTelemetry.rst new file mode 100644 index 0000000000..e343830833 --- /dev/null +++ b/browser/docs/BrowserUsageTelemetry.rst @@ -0,0 +1,148 @@ +.. _browserusagetelemetry: + +======================= +Browser Usage Telemetry +======================= + +The `BrowserUsageTelemetry.jsm <https://searchfox.org/mozilla-central/source/browser/modules/BrowserUsageTelemetry.jsm>`_ module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...). + +The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts). + +Tab and window interactions +=========================== +The usage telemetry module currently measures these interactions with the browser's tabs and windows: + +- *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``); +- *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``); +- *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``). + + +Please see `Scalars.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ for the full list of tracked interactions. + +Customizable UI +=============== + +This telemetry records information about the positions of toolbar items and when +the user interacts with them. It is submitted as scalar values along with the +normal telemetry ping. There are a number of different parts to this telemetry: + +UI Areas +-------- + +For the purposes of this telemetry a set of areas are defined: + +* In the main browser UI: + + * ``menu-bar`` - The main menu. + * ``menu-toolbar`` - The normally hidden toolbar that holds the main menu. + * ``titlebar`` - The optional title bar. + * ``tabs-bar`` - The area where tabs are displayed. + * ``bookmarks-bar`` - The bookmarks toolbar. + * ``app-menu`` - The main application (hamburger) menu. + * ``tabs-context`` - The context menu shown from right-clicking a tab. + * ``content-context`` - The context menu shown from right-clicking the web page. + * ``widget-overflow-list`` - Items that have overflowed the available space. + * ``pinned-overflow-menu`` - Items that the user has pinned to the toolbar overflow menu. + * ``pageaction-urlbar`` - Page actions buttons in the address bar. + * ``pageaction-panel`` - The page action (meatball) menu. + * ``nav-bar-start`` - The area of the navigation toolbar before the address bar. + * ``nav-bar-end`` - The area of the navigastion toolbar after the address bar. + * ``unified-extensions-area`` - The unified extensions panel. + +* In ``about:preferences`` the different cagtegories are used: + + * ``preferences-paneGeneral`` + * ``preferences-paneHome`` + * ``preferences-panePrivacy`` + * ``preferences-paneSearch`` + * ``preferences-paneSearchResults`` + * ``preferences-paneSync`` + * ``preferences-paneContainers`` + +Widget Identifiers +------------------ + +In order to uniquely identify a visual element a set of heuristics are used: + +#. If the element is one of the customizable toolbar items then that item's ID + is used. +#. If the DOM element has an ID set then that is used. +#. If the DOM element's class contains one of ``bookmark-item``, + ``tab-icon-sound`` or ``tab-close-button`` then that is used. +#. If the DOM element has a ``preference`` ``key``, ``command``, ``observes`` or + ``data-l10n-id`` attribute then that is used. +#. If there is still no identifier then this is repeated for the DOM element's + parent element. + +Widget Locations +---------------- + +The keyed scalar ``browser.ui.toolbar_widgets`` records the position of widgets in +the UI. At startup the positions of widgets are collected and recorded by +setting the scalar key ``<widget id>_pinned_<area>`` to true. The widget ID are +the IDs of the elements in the DOM. The area is one of the areas listed above +from the browser UI that can be customised. + +For the areas that can be controlled the scalar keys ``<area>_<off/on/newtab>`` are set. +``newtab`` is special to the Bookmarks Toolbar and is used when the toolbar will only +be shown on the New Tab page. + +Widget Customization +-------------------- + +The scalar ``browser.ui.customized_widgets`` records whenever the user moves a +widget around the toolbars or shows or hides some of the areas. When a change +occurs the scalar with the key ``<widget id>_<action>_<old area>_<new area>_<reason>`` +is incremented. The action can be one of ``move``, ``add`` or ``remove``. Old +area and new area are the previous and now locations of the widget. In the case +of ``add`` or ``remove`` actions one of the areas will be ``na``. For areas that +can be shown or hidden the areas will be ``off`` or ``on``. The reason is a simple +string that indicates what caused the move to happen (drag, context menu, etc.). + +UI Interactions +--------------- + +The scalars ``browser.ui.interaction.<area>`` record how often the use +interacts with the browser. The area is one of those above with the addition of +``keyboard`` for keyboard shortcuts. + +When an interaction occurs the widget's identifier is used as the key and the +scalar is incremented. If the widget is provided by an add-on then the add-on +identifier is dropped and an identifier of the form ``addonX`` is used where X +is a number. The number used is stable for a single session. Every time the user +moves or interacts with an add-on the same number is used but then the numbers +for each add-on may change after Firefox has been restarted. + +Profile Count +============= + +The scalar ``browser.engagement.profile_count`` records how many profiles have +been used by the current Firefox installation. It reports a bucketed result, +which will be 0 if there is an error. The raw value will be reported for 1-10, +but above that, it will report 10 for 10-99, 100 for 100-999, 1000 for +1000-9999, and 10000 for any values greater than that. + +The profile count data for an installation is stored in the root of the +update directory in a file called ``profile_count_<install hash>.json``. The +full path to the file will typically look something like +``C:\ProgramData\Mozilla\profile_count_5A9E6E2F272F7AA0.json``. + +This value is meant to be resilient to re-installation, so that file will not +be removed when Firefox is uninstalled. + +Context menu entrypoints +======================== + +Some context menus are re-used in multiple places. By default, we simply count +the number of interactions per item within a context menu, and do not record +the entrypoint that caused the context menu to open. + +It is possible to opt-in to recording the entrypoint that caused the context +menu to open. This is done by adding an entry to +``ENTRYPOINT_TRACKED_CONTEXT_MENU_IDS``, mapping the ID of the context menu +to a keyed Scalar under ``browser.ui.interaction.``. This scalar is recorded +only if an interaction is recorded within the context menu itself. + +When the keyed scalar is recorded, the key will be a unique ID for the +trigger node that caused the context menu to open. The value is the count +of openings from that trigger node. diff --git a/browser/docs/CommandLineParameters.rst b/browser/docs/CommandLineParameters.rst new file mode 100644 index 0000000000..5ba4e6df8d --- /dev/null +++ b/browser/docs/CommandLineParameters.rst @@ -0,0 +1,29 @@ +======================= +Command Line Parameters +======================= + +Firefox recognizes many (many!) command line parameters. Overview +documentation of these parameters lives here. + +Known parameters +---------------- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Parameter + - Description + * - ``-osint`` + - On Windows, ``-osint`` serves two purposes. Most importantly, it signals + that the command line is untrusted and must be sanitized. Command lines + with ``-osint`` are rejected unless they have a very specific structure, + usually ``firefox.exe -osint -url URL`` or ``firefox.exe -osint + -private-window URL``: refer to `the EnsureCommandLineSafe function + <https://searchfox.org/mozilla-central/rev/ead7da2d9c5400bc7034ff3f06a030531bd7e5b9/toolkit/xre/CmdLineAndEnvUtils.h#196>`_. + These command lines are produced by apps delegating to Firefox, and the + resulting URL may not be correctly quoted. The sanitization process + ensures that maliciously chosen URLs do not add additional parameters to + Firefox. Secondarily, the ``-osint`` parameter signals that Firefox is + being invoked by Windows to handle a URL: generally a registered file + type, e.g., ``.html``, or protocol, e.g., ``https``. diff --git a/browser/docs/index.rst b/browser/docs/index.rst new file mode 100644 index 0000000000..c105c59121 --- /dev/null +++ b/browser/docs/index.rst @@ -0,0 +1,33 @@ +================= +Firefox Front-end +================= + +This is the nascent documentation of the Firefox front-end code. + +.. toctree:: + :maxdepth: 2 + + urlbar/index + BrowserUsageTelemetry + CommandLineParameters + components/enterprisepolicies/docs/index + extensions/formautofill/docs/index + components/newtab/docs/index + components/aboutwelcome/docs/index + installer/windows/installer/index + components/attribution/docs/index + /toolkit/mozapps/defaultagent/default-browser-agent/index + components/migration/docs/index + components/pagedata/docs/index + places/index + components/asrouter/docs/index + search/index + base/tabbrowser/index + touchbar/index + components/uitour/docs/index + branding/docs/index + components/storybook/docs/README.storybook.stories + components/storybook/docs/README.reusable-widgets.stories + components/storybook/docs/README.other-widgets.stories + components/storybook/docs/README.lit-guide.stories + components/storybook/docs/README.xul-and-html.stories diff --git a/browser/docs/overview.rst b/browser/docs/overview.rst new file mode 100644 index 0000000000..26f61ff513 --- /dev/null +++ b/browser/docs/overview.rst @@ -0,0 +1,105 @@ +Firefox for Desktop +=================== + +Desktop architecture +-------------------- + +One of the keys to understanding how Firefox is architected is to know that Gecko is used to render +both web content as well as the UI of the browser. This means that, to a large extent, the UI of +Firefox is made using web technologies like HTML, CSS, and JavaScript. For example, the document +``chrome://browser/content/browser.xhtml`` is the markup for a single Firefox browser window. You +can think of it almost like index.html for a webpage. + +The decision to use Gecko for rendering the UI was made during an era when HTML was not yet +expressive enough or sufficient to build desktop UIs. A different markup language, +`XUL <https://en.wikipedia.org/wiki/XUL>`_, was developed for that purpose instead, which Gecko also +knows how to interpret. Since that time, HTML and CSS has evolved to the point where XUL is not +strictly necessary for most use-cases. Where possible, we have been gradually migrating our UI to +use less XUL and more standard HTML and CSS. + +Reusable UI Widgets +------------------- + +Many of the UI widgets in use in the user interface are built as web components that can be reused. + +:ref:`Read more <Reusable UI widgets>` + +Tabbrowser +---------- + +The tabbrowser component manages the tabs in a browser window. + +:ref:`Read more <tabbrowser>` + +Address Bar +----------- + +The address bar (varyingly also referred to as the Awesome Bar, or Quantum Bar) handles users +entering web addresses including a popup with suggestions from various sources including history, +bookmarks and search engines. + +:ref:`Read more <Address Bar>` + +Search +------ + +The search service manages the list of search engines available in the address bar. + +:ref:`Read more <Search>` + +Places +------ + +The places component includes the database that stores history and bookmarks as well as a set of UI +components that present those to the user. + +:ref:`Read more <Places>` + +Firefox Sync and Application Services +------------------------------------- + +Application services includes the sync engines and Firefox Accounts integration. + +:ref:`Read more <Services>` + +Developer Tools +--------------- + +The developer tools support web developers when building webpages but as the Firefox UI is itself +built using web technologies it is also possible to use the developer tools to debug the Firefox UI. + +:ref:`Read more <Firefox DevTools Contributor Docs>` + +Browser Toolbox +############### + +The Browser Toolbox is a way to launch the developer tools in a separate process so that they can be +used to debug the main browser UI. + +:ref:`Read more <Browser Toolbox>` + +Profiler +######## + +The Firefox Profiler is the way to measure the performance of your code. Go to +`profiler.firefox.com <https://profiler.firefox.com>`__ to enable the button in Firefox and record a +performance profile. These profiles can be uploaded and shared. It can identify slow parts of the +code, and reveal the underlying behavior of how code runs. + +Installer +--------- + +The Windows installer for Firefox is built with NSIS. There are currently no installers for other +operating systems. + +:ref:`Read more <Installer>` + +Application Update +------------------ + +Application Update is responsible for requesting available updates from the update servers, +downloading them, verifying their integrity and then ultimately installing them. A binary patch tool +(bsdiff) is used to reduce the size of update files and update files are delivered in the +bespoke mar (Mozilla ARchive) format. + +:ref:`Read more <Application Update>` |