summaryrefslogtreecommitdiffstats
path: root/browser/docs
diff options
context:
space:
mode:
Diffstat (limited to 'browser/docs')
-rw-r--r--browser/docs/BrowserUsageTelemetry.rst148
-rw-r--r--browser/docs/CommandLineParameters.rst29
-rw-r--r--browser/docs/index.rst31
3 files changed, 208 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..49a5c11175
--- /dev/null
+++ b/browser/docs/index.rst
@@ -0,0 +1,31 @@
+=================
+Firefox Front-end
+=================
+
+This is the nascent documentation of the Firefox front-end code.
+
+.. toctree::
+ :maxdepth: 2
+
+ urlbar/index
+ BrowserUsageTelemetry
+ CommandLineParameters
+ app/pbproxy/docs/index
+ components/enterprisepolicies/docs/index
+ extensions/formautofill/docs/index
+ components/newtab/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/newtab/content-src/asrouter/docs/index
+ search/index
+ base/sslerrorreport/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