summaryrefslogtreecommitdiffstats
path: root/browser/docs/BrowserUsageTelemetry.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:22:09 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:22:09 +0000
commit43a97878ce14b72f0981164f87f2e35e14151312 (patch)
tree620249daf56c0258faa40cbdcf9cfba06de2a846 /browser/docs/BrowserUsageTelemetry.rst
parentInitial commit. (diff)
downloadfirefox-43a97878ce14b72f0981164f87f2e35e14151312.tar.xz
firefox-43a97878ce14b72f0981164f87f2e35e14151312.zip
Adding upstream version 110.0.1.upstream/110.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'browser/docs/BrowserUsageTelemetry.rst')
-rw-r--r--browser/docs/BrowserUsageTelemetry.rst131
1 files changed, 131 insertions, 0 deletions
diff --git a/browser/docs/BrowserUsageTelemetry.rst b/browser/docs/BrowserUsageTelemetry.rst
new file mode 100644
index 0000000000..de7e99a007
--- /dev/null
+++ b/browser/docs/BrowserUsageTelemetry.rst
@@ -0,0 +1,131 @@
+.. _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.